Skip to main content

System Architecture

This page outlines the technical architecture design of HocChungKhoan CMS, detailing data flows, monorepo structure, and database synchronization models.

🏛️ Monorepo Overview​

The project is structured as a Monorepo to simplify code management across the frontend, API Worker, database migrations, and docs inside a single repository:

  • /worker: Source code of the Cloudflare Worker (Hono + Chanfana) serving the JSON API.
  • /frontend: Source code of the Astro frontend application.
  • /migrations: SQL migrations schema files for the Insforge database.
  • /docs: The Docusaurus documentation website (this site).

💾 Database Architecture & Data Sync​

The system utilizes a Double-Database strategy to maximize performance and availability:

  1. Neon Postgres (Source of Truth):
    • Serves as the primary operational database storing master data.
    • Houses source tables for imports, audits, and customer records.
  2. Insforge Postgres (Edge Serving DB):
    • Serves as the read-heavy Edge Database queried by Cloudflare Workers.
    • Decreases global network latency for client requests to sub-millisecond ranges.

Synchronization Flow (Sync Flow)​

When an administrator triggers the /api/sync endpoint:

  1. The Cloudflare Worker invokes the Insforge Edge Function named neon-sync.
  2. The Edge Function compares delta changes from Neon Postgres and commits updates/inserts into Insforge Postgres.
  3. Insforge Postgres is immediately updated and ready to serve query requests.
+─────────────────────+           +──────────────────────+
|  Neon Postgres DB   |           | Insforge Postgres DB |
|  (Source of Truth)  |           |  (Edge Serving DB)   |
+──────────┬──────────+           +──────────▲───────────+
           │                                 │
           │        Sync Delta Flow          │
           +─────────────────────────────────+
                       neon-sync
                     Edge Function

🚀 Runtime Environment​

The API layer is deployed on Cloudflare Workers (V8 isolate sandbox), bringing major performance benefits compared to traditional servers:

  • Zero Cold Starts: Requests are handled almost instantaneously.
  • Auto-scaling: Handles spikes in traffic globally without any manual provisioning.
  • Edge Execution: Code runs in Cloudflare points of presence (PoPs) closest to the end user.