MiniC Architecture Handbook
Tài liệu Kiến trúc & Đặc tả Kỹ thuật • Architecture Handbook & Technical Guidev2.4 — Updated 2026

MiniC Platform Architecture Handbook

Đặc tả kỹ thuật: Kết hợp ZITADEL Self-Hosted (AuthN) và Bảng Members PostgreSQL (AuthZ Single Source of Truth).

Technical Specification: ZITADEL Self-Hosted (AuthN) + Platform PostgreSQL Members Single Source of Truth (AuthZ).

1. Kiến trúc Tổng thể & Phân tách Hai Tầng • High Level Design & Separation of Planes

Kiến trúc MiniC áp dụng nguyên tắc phân tách trách nhiệm tuyệt đối giữa hai tầng: ZITADEL đảm nhiệm Xác thực danh tính (AuthN), trong khi Core Platform quản lý toàn bộ Phân quyền (AuthZ) dựa trên bảng members trong PostgreSQL.

The MiniC architecture enforces strict Separation of Concerns: ZITADEL handles 100% of Authentication (AuthN), while Platform Core owns 100% of Authorization (AuthZ) backed by the PostgreSQL members table.

SƠ ĐỒ LUỒNG KIẾN TRÚC DỮ LIỆU & BẢO MẬT • SYSTEM ARCHITECTURE & SECURITY TOPOLOGY
1. Client / Browser• WebAuthn FIDO2 Ceremony• Passwordless Biometrics• OIDC Code Flow + PKCE• Header: X-Org-Id (X-Mn-Org-Id)User Identitydev@demo.localOrg: org_c_digitalAuthN: /v2/sessions2. ZITADEL IAM (AuthN)• Instance: zitadel.cakedemo.site• FIDO2 Hardware Attestation• Password Verification Engine• M2M Machine JWT ProfileAssertion OutputSubject: dev@demo.local✔ Zero AuthZ decisionsListMemberships3. Platform Core (AuthZ)• Table: public.members• Table: public.organizations• Rules: pkg/authz/perm• Scopes: console.app.writePostgreSQL ResolutionRole: DEVELOPER (Active)Org: org_c_digital (Admit)

Tầng Xác thực (AuthN): ZITADEL Self-Hosted • Authentication Plane

Chịu trách nhiệm 100% về vòng đời đăng nhập, định danh người dùng và xác thực sinh trắc học.

100% responsible for login ceremonies, credential lifecycles, and hardware biometric authentication.

  • Chuẩn FIDO2 WebAuthn Level 3 (Touch ID, Face ID, YubiKey) — FIDO2 WebAuthn Level 3 compliant hardware credentials.
  • Quản trị tập trung với UI Angular nhúng sẵn (/ui/console) — Native built-in Angular management console at /ui/console.
  • Không chứa bất kỳ quyền hạn ngân hàng nào (Zero privilege escalation) — Zero banking authority: does not assign permissions.

Tầng Phân quyền (AuthZ): Platform Core Database • Authorization Plane

Nguồn sự thật duy nhất (Single Source of Truth) về tổ chức, vai trò và phân quyền nghiệp vụ.

Single Source of Truth for organizations, member roles, and granular banking permissions.

  • Truy vấn (Query): SELECT * FROM members WHERE subject = LOWER($email) AND status = 'ACTIVE';
  • Hai vai trò duy nhất (Roles): DEVELOPER (full write) và VIEWER (read-only) — Exactly two roles.
  • Chế độ fail-closed: User chưa có record hoặc SUSPENDED bị chặn 403 ngay lập tức — Fail-closed: unlinked or SUSPENDED members blocked with 403.