Sơ đồ & Mô tả Kiến trúc Chi tiết

Mã tài liệu:	EZD-TEC-ARCH	Phiên bản:	1.0
Ngày hiệu lực:	20/09/2025	Người soạn:	Stephen
Người phê duyệt:	Stephen	Trang:	1/X

1. Context (C0) – Toàn cục

flowchart LR
  subgraph Tenant
    AP[Anh Phong<br/>Tenant Admin]
    SA[Super Admin]
  end

  User[Khách tham quan<br/>Chị An] -->|Hỏi/Nghe| Booth[Booth App<br/>Kiosk]
  AP -->|Quản trị nội dung| AdminWeb[Admin Webapp<br/>CMS + Dashboard]
  SA -->|RBAC/User mgmt| AdminWeb

  AdminWeb -->|CRUD nội dung/branding/FAQ/promo| API_GW[API Gateway]
  Booth -->|NLP/Query/Trả lời| API_GW

  API_GW -->|Route| S1[Backend Service <br/>CMS/Dashboard]
  API_GW -->|Route| S2[AI Core Service]

  S1 <--> KB[(Knowledge Base)]
  S1 --> LDB[(Logging DB)]
  S2 -->|Query dữ liệu| KB
  S2 -->|Call| Gemini[Google Gemini API]
  S2 --> LDB

  AdminWeb <-->|Số liệu/biểu đồ| S1
  Booth <-->|Kết quả/Map/List/General| S2

Ghi chú ràng buộc: mọi response phải kèm meta.requestId/traceId/timestamp và echo header X-Request-Id/X-Trace-Id để trace xuyên các service (đã quy định trong api_standards.md).

---

2. Container (C1) – Các Microservices & Kho dữ liệu

flowchart TB
    subgraph Edge["Thiết bị & Giao diện"]
        Booth["Booth App (Kiosk UI)\n• Voice + Map + Promo\n• Persona: Chị An"]
        AdminWeb["Admin Webapp (CMS + Dashboard)\n• Persona: Anh Phong"]
    end

    subgraph Cloud["EZD Cloud Platform"]
        API_GW["API Gateway\n• AuthN/AuthZ cơ bản\n• Routing\n• Rate-limit"]

        subgraph CoreServices["Core Services"]
            AICore["AI Core Service\n• Retrieval Engine\n• Orchestrator\n• NLU Client (Gemini)\n• Cache Handler\n• Logging"]
            Backend["Backend Service\n• CMS API (Promo, FAQ, Branding, Avatar)\n• Dashboard API (Logs, Stats)\n• Auth (JWT issue/refresh)\n• RBAC Mgmt\n• Notifier Adapter"]
        end

        subgraph DataLayer["Data Layer"]
            KB["Knowledge Base (DB Chính)\n• FAQ/Promo/Map/Branding"]
            Cache["Cache Layer\n• Redis/memcached\n• TTL sync ≤1 phút"]
            LogDB["Logging DB\n• Interaction logs\n• Telemetry\n• Audit"]
        end

        subgraph Ext["Dịch vụ Bên ngoài"]
            Gemini["Google Gemini API\n(NLU, Reasoning)"]
            Alert["Alert Service\n(Email/Chat)"]
        end
    end

    %% Flows
    Booth -->|Voice/Text Query| API_GW
    AdminWeb -->|CRUD Content/Stats| API_GW

    API_GW --> AICore
    API_GW --> Backend

    AICore --> KB
    AICore --> Cache
    AICore --> Gemini
    AICore --> LogDB
    AICore --> Alert

    Backend --> KB
    Backend --> Cache
    Backend --> LogDB
    Backend --> Alert

    AdminWeb <-->|Charts/Logs| Backend
    Booth <-->|Answers/Map/Promo| AICore

    %% Chú thích (dùng node riêng)
    NoteBackend["📌 Auth & RBAC\nJWT issuance + refresh\nSuper Admin / Tenant Admin"]
    Backend -.-> NoteBackend

    NoteCache["📌 Sync ≤1 phút\nCMS update → invalidate cache\nBooth đọc cache mới"]
    Cache -.-> NoteCache

    NoteAICore["📌 Fallback Strategy\nNếu Gemini lỗi/timeout → KB-only answer\n+ Thông điệp resilience"]
    AICore -.-> NoteAICore

Chuẩn API bắt buộc áp dụng: versioning /v1, grouping theo tags, phân trang limit/offset, sort, filter[...], bộ response success/error chuẩn và các response codes phổ biến 2xx/4xx/5xx (đã đóng gói sẵn trong template).

---

3. Container (C2) - Component Diagram

flowchart TB
    subgraph AI_Core["AI Core Service"]
        Orchestrator["Orchestrator\n• Nhận request từ API GW\n• Chọn pipeline xử lý\n• Fallback khi Gemini lỗi"]
        Retrieval["Retrieval Engine\n• Query KB\n• Áp dụng cache layer\n• Kết hợp context"]
        NLUClient["NLU Client\n• Call Google Gemini API\n• Intent/Entity extraction"]
        CacheHandler["Cache Handler\n• Read/Write cache\n• TTL ≤ 1 phút"]
        LoggerAI["Logging Module\n• Ghi interaction\n• Latency, error, retry"]
    end

    subgraph Backend["Backend Service"]
        CMS_API["CMS API\n• CRUD Promo\n• CRUD FAQ\n• CRUD Branding\n• CRUD Avatar"]
        Dashboard_API["Dashboard API\n• Lấy logs/statistics\n• Top Qs, Heatmap"]
        AuthModule["Auth Module\n• JWT issuance/refresh\n• Password reset\n• RBAC Enforcement"]
        RBACModule["RBAC Module\n• Manage roles/permissions\n• Super Admin / Tenant Admin"]
        Notifier["Notifier Adapter\n• Email/Chat alert\n• Booth offline, error"]
        LoggerBE["Logging Module\n• Audit logs\n• CMS/Dashboard ops"]
    end

    subgraph DataLayer["Data Layer"]
        KB[(Knowledge Base)]
        Cache[(Cache Layer)]
        LogDB[(Logging DB)]
    end

    subgraph Ext["Dịch vụ Bên ngoài"]
        Gemini["Google Gemini API"]
        Alert["Alert Service (Email/Chat)"]
    end

    %% AI Core flows
    Orchestrator --> Retrieval
    Orchestrator --> NLUClient
    Orchestrator --> LoggerAI
    Retrieval --> KB
    Retrieval --> CacheHandler
    CacheHandler --> Cache
    NLUClient --> Gemini
    LoggerAI --> LogDB

    %% Backend flows
    CMS_API --> KB
    CMS_API --> Cache
    CMS_API --> LoggerBE
    Dashboard_API --> LogDB
    Dashboard_API --> LoggerBE
    AuthModule --> RBACModule
    AuthModule --> LoggerBE
    RBACModule --> LoggerBE
    Notifier --> Alert
    LoggerBE --> LogDB

Giải thích bổ sung:

• AI Core Service

• Orchestrator: “não trung tâm” quyết định pipeline.

• Retrieval Engine: query KB (FAQ, Promo, Map), có cache TTL ≤ 1 phút.
• NLU Client: gọi Gemini để detect intent/entity.
• Cache Handler: invalidate khi Backend update.

• Logger: ghi đầy đủ interaction, latency, error.

• Backend Service

• CMS API: quản trị nội dung (Promo/FAQ/Branding/Avatar).

• Dashboard API: thống kê/logs cho Tenant.
• Auth Module: cấp JWT, refresh token, reset mật khẩu.
• RBAC Module: quản lý role/permission.
• Notifier: gửi alert (booth offline > 15 phút, lỗi sync, lỗi Gemini).
• Logger: audit ops, security logs.

---

4. Luồng Dữ liệu Chi tiết (điểm nhấn 2 đường quan trọng)

4.1. Luồng CMS → Knowledge Base

Mục tiêu: Tenant cập nhật nội dung (FAQ/Promotion/Branding/Avatar) và hệ thống sync sang Booth ≤ 1 phút (đã ràng buộc trong backlog & screen spec).

• Admin Webapp gửi POST/PUT/PATCH/DELETE tới CMS/Dashboard API qua API Gateway.
• Backend Service validate → ghi KB (Knowledge Base) → ghi LogDB → bắn Notifier (nếu có).
• API response chuẩn có status/meta{requestId,traceId,timestamp} và header X-Request-Id / X-Trace-Id để trace end-to-end.
• Ràng buộc SLA “Booth phản ánh thay đổi ≤ 1 phút” đã được đặt ở các user story/screen (FAQ/Branding/Avatar).

sequenceDiagram
  autonumber
  participant AP as Admin Webapp (Tenant)
  participant GW as API Gateway
  participant CMS as Backend Service (CMS/Dashboard)
  participant KB as Knowledge Base
  participant L as Logging DB
  participant N as Notifier

  AP->>GW: POST /v1/faqs (Bearer, X-Request-Id)
  GW->>CMS: Route (AuthZ, Rate-limit)
  CMS->>KB: Upsert FAQ record
  CMS->>L: Append audit log
  CMS-->>AP: 201 {status:"success", meta{requestId,traceId,...}}
  Note over CMS,AP: Headers echo: X-Request-Id, X-Trace-Id
  CMS->>N: (Optional) 'Content updated' alert

4.2. Luồng AI Core → KB + Google Gemini

Mục tiêu: Booth trả lời nhanh, chính xác; AI Core truy vấn KB + gọi Google Gemini API khi cần reasoning/NLG, sau đó trả kết quả về Booth.

• Booth gửi query (intent) → API Gateway → AI Core.
• AI Core: Retrieval từ KB (+ Cache nóng) → prompt orchestration → gọi Gemini → hợp nhất → trả về kết quả + meta/headers chuẩn → ghi LogDB.
• Các màn hình kết quả (Map/List/General) đã đặc tả rõ UI/UX (Booth App).

sequenceDiagram
  autonumber
  participant U as User @ Booth
  participant B as Booth App
  participant GW as API Gateway
  participant AI as AI Core Service
  participant C as Cache
  participant KB as Knowledge Base
  participant G as Google Gemini API
  participant L as Logging DB

  U->>B: Voice/Text Query
  B->>GW: POST /v1/ask (Bearer, X-Request-Id)
  GW->>AI: Route (AuthZ, Rate-limit)
  AI->>C: Check cached retrieval (optional)
  AI->>KB: Retrieve relevant docs
  AI->>G: Compose prompt & call Gemini
  G-->>AI: Completion / Tool outputs
  AI->>L: Log Q/A + telemetry
  AI-->>B: 200 {status:"success", data:answer, meta{requestId,traceId}}
  Note over AI,B: Echo headers: X-Request-Id, X-Trace-Id

---

5. Liên kết với Đặc tả API .yaml (Booth/CMS/Dashboard/Common)

• Mẫu OpenAPI chuẩn (paths/responses/schemas/headers/security) đã được template hóa để tái sử dụng giữa các service.
• Envelope response chuẩn với status=success|error, meta chứa requestId/traceId/timestamp, danh sách có pagination.
• Headers bắt buộc: X-Request-Id, X-Trace-Id, X-RateLimit-*, và (khi cần) ETag/If-Match cho optimistic locking.

---

6. Guardrails vận hành then chốt (trích từ backlog/screen)

• Sync latency ≤ 1 phút từ CMS → Booth cho FAQ/Branding/Avatar.
• RBAC/User Management có guardrails tránh xóa role đang dùng và Super Admin cuối cùng.

---

7. Gợi ý hiện thực hóa nhanh (không ràng buộc vendor)

• API Gateway: tập trung AuthN/AuthZ, rate-limit, request-id injection, và chuẩn hóa headers/observability theo api_standards.md.
• AI Core: module hóa Retrieval (KB), Orchestrator (prompt + tools), LLM client (Gemini), Cache nóng cho kết quả retrievable.
• Backend Service (CMS/Dashboard): expose endpoints CRUD (promo/faq/branding/avatar/user/rbac), emit event để Booth sync nhanh, log đầy đủ vào Logging DB.

• Data Layer:

• Knowledge Base: nguồn duy nhất (single source of truth) cho nội dung hiển thị Booth.

• Logging DB: lưu audit/telemetry, hỗ trợ Dashboard.
• Cache: tăng tốc truy hồi knowledge (đặc biệt FAQ/popular queries).

---

8. Kết nối QMS & Traceability

• QMS: checklist & tiêu chí chấp nhận đã đính trong user stories/screens; kiến trúc này đảm bảo các điểm đo (latency, success rate, retry) có thể quan sát được qua Logging DB + headers meta.
• Trace mapping (gợi ý): Persona/Journey → User Story → Screen Spec → API Endpoint → Log event → Dashboard chart.