02 — Kiến trúc & sơ đồ liên kết

1. Tổng quan hệ thống

flowchart TB
  subgraph Clients["Clients (FE)"]
    C[Consumer · mobile/]
    P[Partner · partner/]
    Dr[Driver · driver/]
    Ad[Admin Dashboard · dashboard/]
  end

  subgraph Edge["Ubuntu edge"]
    Nx[Nginx TLS]
  end

  subgraph API["NestJS api/"]
    Auth[auth JWT RBAC]
    Vert[vertical modules]
    Plat[platform modules]
    GW[WebSocket gateway]
    SW[Swagger /docs]
  end

  subgraph Data["Data plane"]
    PG[(PostgreSQL + PostGIS)]
    RD[(Redis)]
    S3[(MinIO / S3)]
  end

  subgraph Ext["External"]
    Maps[Maps / Routing]
    Pay[MoMo · VNPay]
    SMS[OTP SMS]
    FCM[FCM Push]
    LLM[AI LLM]
  end

  C --> Nx
  P --> Nx
  Dr --> Nx
  Ad --> Nx
  Nx --> Auth
  Auth --> Plat
  Auth --> Vert
  Plat --> GW
  Vert --> GW
  Plat --> PG
  Vert --> PG
  Auth --> RD
  Plat --> S3
  Vert --> Maps
  Vert --> Pay
  Auth --> SMS
  Plat --> FCM
  Vert --> LLM
  SW -.-> Auth

2. Phân lớp trách nhiệm (quy chuẩn)

Lớp	Được phép	Cấm
FE Consumer/Partner/Driver	UI, navigation, gọi API/WS, maps SDK, validate form	Tính giá cước, matching, trừ ví, duyệt KYC
Admin Dashboard	Ops UI, filter/report, gọi API admin	SQL trực tiếp, bypass RBAC
BE	Business, ledger, geo, matching, aggregation	Hardcode UI layout
DB	Source of truth	FE ghi thẳng

3. Luồng đặt dịch vụ (mẫu — áp mọi vertical có order)

sequenceDiagram
  participant U as Consumer FE
  participant A as API
  participant M as Merchant/Partner FE
  participant D as Driver FE optional
  participant W as Wallet/Payments

  U->>A: POST quotes / browse
  A-->>U: prices · availability
  U->>A: POST order/booking
  A->>W: hold / charge
  A-->>M: WS new order
  M->>A: accept / reject
  opt Delivery
    A-->>D: assign
    D->>A: status updates
  end
  A-->>U: tracking WS
  U->>A: rate
  A-->>M: review notify

4. RBAC liên kết surface

flowchart LR
  USER --> Consumer
  DRIVER --> DriverApp
  PARTNER_OWNER --> PartnerApp
  PARTNER_STAFF --> PartnerApp
  ADMIN --> Dashboard
  DOCTOR --> PartnerClinic
  LANDLORD --> PartnerLandlord

  Consumer --> API
  DriverApp --> API
  PartnerApp --> API
  Dashboard --> API
  PartnerClinic --> API
  PartnerLandlord --> API

Mọi request: Authorization: Bearer <access> · Guard JwtAuthGuard + RolesGuard.

5. Hợp đồng realtime

Channel	Publisher	Subscriber
`trip:{id}`	rides/driver	Consumer, Driver
`order:{storeId}`	orders	Partner F&B/Pharmacy
`conversation:{id}`	chat	các bên chat
`parking:{lotId}`	parking partner	Partner parking, optional Consumer

Thông báo (inbox + push + WS): architecture/NOTIFICATION-SYSTEM.md · WP-NOTIF-HUB-01. GPS chỉ WS; booking không SMS.

6. Deploy Ubuntu (liên kết runtime)

Xem UBUNTU-DEPLOY.md. Chuỗi: Nginx → NestJS → Postgres/Redis/MinIO.