Chuyển tới nội dung chính

Kiến trúc Hệ thống

Trang này mô tả chi tiết thiết kế kiến trúc kỹ thuật của hệ thống HocChungKhoan CMS, bao gồm luồng dữ liệu, phân chia monorepo và mô hình đồng bộ database.

🏛️ Tổng quan Monorepo​

Dự án được tổ chức dưới dạng Monorepo để dễ dàng quản lý code frontend, API Worker và database migrations trong cùng một repository:

  • /worker: Chứa source code của Cloudflare Worker (Hono + Chanfana), chịu trách nhiệm cung cấp API.
  • /frontend: Chứa mã nguồn Astro Frontend để hiển thị Dashboard người dùng cuối.
  • /migrations: Lưu trữ các file SQL migrations cho Insforge database.
  • /docs: Trang tài liệu Docusaurus (site này).

💾 Kiến trúc Database & Đồng bộ dữ liệu​

Hệ thống sử dụng mô hình Double-Database để tối ưu hóa hiệu năng và độ tin cậy:

  1. Neon Postgres (Source of Truth):
    • Đóng vai trò là database chính lưu trữ dữ liệu.
    • Chứa các bảng gốc phục vụ cho quá trình import sao kê, quản lý khách hàng.
  2. Insforge Postgres (Edge Serving DB):
    • Đóng vai trò là Serving Database để Cloudflare Worker truy vấn trực tiếp ở Edge.
    • Giúp giảm thiểu tối đa độ trễ mạng (Network Latency) cho người dùng cuối.

Luồng Đồng bộ (Sync Flow)​

Khi Admin hoặc hệ thống kích hoạt API /api/sync:

  1. Cloudflare Worker gọi đến Edge Function của Insforge có tên neon-sync.
  2. Edge Function thực thi việc so sánh các thay đổi từ Neon Postgres và đồng bộ các hàng mới/cập nhật vào Insforge Postgres.
  3. Database Insforge được cập nhật tức thì và sẵn sàng phục vụ các API tiếp theo.
+─────────────────────+           +──────────────────────+
|  Neon Postgres DB   |           | Insforge Postgres DB |
|  (Source of Truth)  |           |  (Edge Serving DB)   |
+──────────┬──────────+           +──────────▲───────────+
           │                                 │
           │           luồng sync            │
           +─────────────────────────────────+
                       neon-sync
                     Edge Function

🚀 Môi trường Triển khai (Runtime)​

Lớp API chạy trên môi trường Cloudflare Workers (V8 isolate sandbox), mang lại nhiều lợi thế vượt trội so với server truyền thống:

  • Không khởi động lạnh (Zero Cold Starts): Phản hồi request gần như ngay lập tức.
  • Tự động mở rộng (Auto-scaling): Đáp ứng hàng triệu request đồng thời mà không cần cấu hình cụ thể.
  • Chạy gần người dùng (Edge Routing): Request được định tuyến đến datacenter Cloudflare gần người dùng nhất trên toàn cầu.