§1. KIẾN TRÚC DỮ LIỆU — 4 DATABASE + 3 LỚP NÃO-KHO-CỔNG

Part of: PG Reform Tools — S176 mission Prev: 00-index.md ← | → Next: 02-k0-k1-timeline-channels.md

---

§1.1 Cụm PostgreSQL — 4 Database

PostgreSQL 16 chạy trên VPS Contabo EU làm nền tảng dữ liệu DUY NHẤT. Cluster có 4 database với vai trò khác nhau hoàn toàn, KHÔNG được gom thành 1.

#	Database	Owner	Tables	Vai trò	Lớp	Gateway hợp pháp
1	directus	workflow_admin	138+	Business warehouse — Directus CMS, mọi bảng nghiệp vụ user nhập, mọi managed collections (workflows, tasks, modules, system_issues, meta_catalog, knowledge_documents, registry tables, governance, KG, normative...), mọi PG function/trigger phục vụ Directus	Lớp KHO	Directus REST API + DOT chính thức + PG function fn_*
2	incomex_metadata	workflow_admin	9	Agent Data store — kb_documents, kb_documents_history, kb_audit_log, metadata_store, chat_messages, cron_heartbeat, kb_config, trigger_guard_alerts, trigger_guard_exceptions. Bản chất NoSQL-style upsert, tương thích Qdrant vector	Lớp NÃO	Agent Data FastAPI (pg_store.py) — cổng riêng, KHÔNG qua Directus
3	workflow	workflow_admin	0 (rỗng)	Placeholder workflow engine — RỖNG có chủ đích. Để dành cho Kestra/Temporal/workflow engine giai đoạn sau (theo data-connection-law.md v1.1 Điều 4 — đã đưa lên hiến pháp v4.5.0)	Lớp ENGINE (chưa active)	Sẽ định khi engine kích hoạt
4	postgres	workflow_admin	system	Default cluster admin DB — không chứa dữ liệu nghiệp vụ. Chỉ dùng admin cluster	—	Không truy cập trực tiếp

Lý do KHÔNG gom 4 DB:

• incomex_metadata riêng để Agent Data có thể vận hành độc lập, NoSQL-style upsert mà không vướng Directus schema constraints
• workflow riêng để workflow engine tương lai có không gian riêng, không trộn với business data
• directus riêng để Directus CMS làm SSOT business data sạch
• Gom = vi phạm "tách dữ liệu gốc khỏi hiển thị" + "không trộn vai trò 3 lớp" + phá kiến trúc đã được Owner phê duyệt từ S100

---

§1.2 Ba Lớp Kiến trúc — Não, Kho, Cổng

Nguyên tắc: Không trộn vai trò. Mỗi thành tố nằm rõ ở 1 lớp chính. Luồng dữ liệu: Cổng → Não → Kho (hoặc ngược lại khi hiển thị).

Lớp NÃO (Brain) — Suy luận, AI, vector search

Vai trò: Đọc tri thức, sinh phản hồi, điều khiển CI/CD. KHÔNG là SSOT cho dữ liệu lâu dài.

Thành tố:

• Agent Data FastAPI (Docker container, VPS) — orchestrator AI, gọi Qdrant + đọc/ghi incomex_metadata
• Qdrant (Docker container, VPS) — vector store cho embedding tri thức, tìm kiếm semantic
• AI agents IDE (Cursor, Codex, Gemini CLI, Claude Code, Claude Desktop) — gọi API, không lưu trữ lâu dài, sinh mã, sửa mã, điều khiển CI/CD

Lớp KHO (Warehouse) — Bản ghi chính thức, SSOT

Vai trò: Lưu trữ chính thức, schema enforce, version, audit, phân quyền.

Thành tố:

• PG DB directus — SSOT cho mọi business records (workflows, tasks, system_issues, meta_catalog, knowledge_documents, registry, governance, KG)
• PG DB incomex_metadata — SSOT cho Agent Data document store
• Directus CMS (port 8055) — gateway chính thức cho directus DB, áp dụng 3 vùng schema (Core/Migration/Growth)
• GitHub — SSOT cho mã nguồn (Nuxt, DOT scripts, infra YAML, Terraform); GitHub là đường ống push→VPS, không phải runtime SSOT
• GCP Secret Manager (GSM) — SSOT cho mọi secret (PG password, API token, service account key)

Lớp CỔNG (Gate) — Giao diện người, hệ thống ngoài

Vai trò: Thu nhận input người, hiển thị output. KHÔNG là SSOT, KHÔNG truy cập DB trực tiếp (trừ deploy hook hợp pháp ghi §15 Điều 33).

Thành tố:

• Nuxt Web (https://vps.incomexsaigoncorp.vn) — portal hiển thị, đọc Directus REST/GraphQL qua nuxt-directus
• Directus Admin UI (port 8055) — admin nội bộ thao tác business data
• Lark Suite (Base, Docs, Sheets, Messenger) — nguồn dữ liệu nghiệp vụ thực, sync 2 chiều với Directus qua DOT chuyên biệt
• Chatwoot (planned) — CSKH đa kênh, sẽ tích hợp khi active
• GitHub Actions — CI/CD, push qua SSH→VPS deploy

---

§1.3 Tham chiếu

• Hiến pháp v4.5.0 — phần "KIẾN TRÚC HẠ TẦNG DỮ LIỆU"
• Điều 33 v2.0 §0 — "Kiến trúc 4 DB + 3 lớp Não-Kho-Cổng"
• data-connection-law.md v1.1 — đã SUPERSEDED, nội dung kế thừa nguyên vẹn lên hiến pháp v4.5.0

---

File 01 — §1 Kiến trúc | Index | S176 | Living doc