Skip to content

Kiến trúc tham chiếu nền tảng MINAP ​

Version: 1.0
Date: 2026-11-12
Status: Working baseline

1. Mục tiêu ​

Xây dựng nền tảng đa Application cho người dùng một tài khoản và điểm vào nhất quán, đồng thời cho phép từng Application phát triển độc lập. Giữ MVP vận hành được với đội nhỏ và tránh biến mọi khả năng thành microservice quá sớm.

2. Kiến trúc logic ​

Đây là bản đồ khả năng logic, không phải lệnh triển khai mỗi ô thành microservice độc lập ngay ngày đầu. Các khả năng liên quan chặt có thể tạm chia sẻ một deployable trong khi vẫn giữ rõ module và quyền sở hữu dữ liệu.

Luồng định tuyến (hướng DECIDED): Nginx luôn là edge công khai. Traefik không nằm trên đường mặc định — chỉ các dịch vụ lộ UI end-user quan trọng và cần cutover Blue-Green / zero-downtime mới đi Nginx → Traefik → Swarm.

3. Trách nhiệm Platform Core ​

Trong phạm vi

  • Tích hợp identity tài khoản và điều phối vòng đời tài khoản.
  • Primitive Personal Workspace và Organization Workspace.
  • Membership Workspace và vai trò cấp nền tảng.
  • Catalog, discovery, launch Application và navigation chung.
  • Primitive subscription/entitlement và quyết định truy cập Application.
  • Cấu hình dùng chung và hợp đồng tích hợp nền tảng.
  • Audit và sự kiện vận hành nền tảng.
  • Registry/cấu hình tích hợp cho các khả năng dùng chung.

Ngoài phạm vi

  • Sở hữu mọi entity domain của từng Application.
  • Triển khai tập trung mọi workflow nghiệp vụ.
  • Cung cấp truy cập database trực tiếp không hạn chế giữa các Applications.
  • Trở thành hệ thống accounting, CRM hoặc ERP đa năng.

4. Trách nhiệm Application ​

Mỗi Application sở hữu:

  • Domain model và quy tắc nghiệp vụ của mình.
  • Roles và permissions riêng của Application trong một Workspace.
  • Khái niệm membership/assignment riêng của Application.
  • UI và workflow của Application.
  • Báo cáo cấp Application và audit theo domain.
  • Vòng đời release và lựa chọn công nghệ riêng, tuân thủ hợp đồng nền tảng.

Một Application có thể dùng Next.js, Angular, PHP hoặc stack được hỗ trợ khác. Tích hợp phải dựa trên HTTP APIs đã tài liệu hóa, chuẩn OIDC/OAuth và hợp đồng SDK, không giả định framework dùng chung.

5. Baseline triển khai ​

DECIDED

  • Docker Swarm vẫn là môi trường orchestration triển khai.
  • Nginx luôn là edge công khai: chấm dứt TLS, định tuyến host/path, và reverse proxy duy nhất hướng Internet.
  • Traefik là hop thứ hai tùy chọn phía sau Nginx cho các dịch vụ hướng người dùng được chọn cần Swarm service discovery, dynamic routing/LB và cutover Blue-Green gần zero downtime.
  • Đường mặc định không đi qua Traefik.

5.1 Hai luồng ingress ​

FlowĐường điDùng khiMục tiêu điển hình
1 — Nginx trực tiếpClient → Nginx → Docker Swarm (published port / fixed upstream / VIP)Mặc định. UI chỉ cho operator, bề mặt nội bộ/admin, API không có UX end-user, dịch vụ chấp nhận restart ngắn hoặc chuyển upstream thủ côngAdmin sites; Platform Core / Application APIs; webhooks; endpoint hướng worker
2 — Nginx + TraefikClient → Nginx → Traefik → Docker SwarmWeb/portal end-user quan trọng nơi downtime dễ thấy; Blue-Green với chuyển router TraefikMINAP App Shell / customer portals; Application user UIs (ví dụ UI khách/nhân viên Salon khi đã productize)

5.2 Quy tắc phân loại ​

  • Flow 1 theo mặc định. Chỉ chọn Flow 2 khi bề mặt là UX người dùng thấy được và cutover release phải gần zero downtime.
  • API và admin ở Flow 1 trừ khi Owner quyết định nâng một bề mặt cụ thể lên Flow 2 (hiếm).
  • Blue-Green (D-007) bắt buộc cho cutover Flow 2 qua Traefik (hai stack / colored labels; Traefik chuyển traffic; rollback nhanh bằng chuyển lại). Flow 1 có thể dùng restart đơn giản, rolling update, hoặc đổi Nginx upstream — downtime phải chấp nhận được với đối tượng đó.
  • Nginx vẫn chấm dứt TLS và áp dụng chính sách edge cho cả hai flow; Traefik không được lộ làm edge công khai.
  • Một dịch vụ có thể nâng cấp Flow 1 → Flow 2 khi trở thành portal end-user quan trọng; ghi thay đổi vào sổ quyết định / ops runbook.

5.3 Ghi chú vận hành ​

  • MINAP có cấu hình, secrets, networks và vòng đời triển khai độc lập; tái sử dụng pattern vận hành đã chứng minh, không tái sử dụng identity runtime hay state của dự án khác.
  • Secrets và ENV (D-016): dùng open-source Infisical (ưu tiên self-hosted) làm SoT. Inject vào Swarm/services và CI qua cơ chế Infisical đã duyệt. Không commit secrets, private key, hay file production ENV vào git; override local của developer không được trở thành nguồn chuẩn dùng chung.
  • Hostname chính xác, Traefik labels, đặt tên stack blue/green và map Nginx upstream là chi tiết triển khai cho Infra — giữ trong docs deploy theo từng repo, nhất quán với baseline này.

6. Quyền sở hữu dữ liệu ​

  • Platform Core sở hữu tham chiếu identity nền tảng, bản ghi workspace, memberships, application registry và entitlements nền tảng.
  • Mỗi Application sở hữu database/schema domain của mình.
  • File Service sở hữu metadata file trong database riêng (display name, size, type, storage_key chung local/cloud, ownership, lifecycle) và ánh xạ tới object storage cho bytes; bản ghi nghiệp vụ giữ tham chiếu file_id ổn định.
  • Chat sở hữu trạng thái giao tiếp qua triển khai Matrix đã chọn và lớp tích hợp.
  • Payment Integration sở hữu giao dịch/intent payment đã chuẩn hóa và xử lý sự kiện nhà cung cấp theo thiết kế payment đã thống nhất.
  • Invoice Integration sở hữu cấu hình connector và bản ghi đồng bộ, không sở hữu sổ bán hàng của Application trừ khi được thiết kế tường minh.

7. Business identifiers (D-017) ​

  • ID nghiệp vụ ổn định công khai là string, không dùng integer auto-increment của database.
  • Format: {prefix}_{nanoid} với một alphabet và length NanoID thống nhất toàn platform (giá trị cụ thể còn OPEN đến khi ghi sổ prefix).
  • Prefix minh họa: acc_ (MINAP Account), org_ (organization khi tách riêng), ws_ (Workspace), file_ / tmp_ (File Service — file publish, upload tạm; không prefix cho storage_connections), app_ (id Application đăng ký cho SDK/API credentials, D-018), cộng thêm prefix domain riêng của từng Application theo contract của Application đó. Chi tiết FS: /architecture/database/02-file-service §4.
  • ID được sinh phía server; client không được tự tạo ID.
  • Liệt kê theo thời gian / range query dùng created_at (và timestamp tương tự), không dựa thứ tự lexicographic của ID.
  • Bắt buộc prefix khi ID là identifier MINAP ổn định lộ trên API, SDK, URL, webhook hoặc log xuyên service.
  • Bỏ prefix chỉ khi: ID thuần nội bộ implementation không bao giờ ra khỏi service; hoặc identifier của vendor ngoài (Keycloak sub, Matrix ID, payment/invoice provider ID) lưu opaque và map sang MINAP ID có prefix.
  • Prefix giúp nhận diện và validate; không thay authorization.

8. Yêu cầu xuyên suốt ​

  • OIDC/OAuth2 cho authentication user; lời gọi Application dùng Platform API credentials (app_… + token, D-018) do Platform Core cấp — tường minh, audit được, chỉ backend.
  • Ngữ cảnh Workspace phải được xác thực phía server; không bao giờ tin workspace ID do client cung cấp một mình.
  • Mọi API phải định nghĩa authorization, mô hình lỗi, nhu cầu idempotency, pagination và versioning.
  • Secrets và environment variables phải tách khỏi mã nguồn và quản lý trong Infisical (D-016), rồi inject lúc deploy/runtime.
  • Audit các hành động đặc quyền, thay đổi membership, chuyển trạng thái payment và truy cập file khi phù hợp.
  • Dùng log có cấu trúc (structured logs), health/readiness endpoints, metrics và correlation trace.
  • Backup và kiểm thử restore bắt buộc trước khi onboard dữ liệu production.

9. Quyết định kiến trúc còn mở ​

  • Monorepo so với các repository độc lập.
  • Phân rã triển khai/module Platform Core chính xác.
  • Event broker và đảm bảo phân phối sự kiện.
  • Gán Flow 1 vs Flow 2 theo từng service ngoài quy tắc phân loại ở trên (bản đồ hostname / inventory Traefik label).
  • Composition frontend shell chính xác; UI kit là D-020 (platform-ui, shadcn-like web kit trên Next.js, Mobile-First, RN WebView shell).
  • Công nghệ và topology database theo từng thành phần.
  • Tham số NanoID chuẩn và sổ prefix (D-017).

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English