KB-3C90
Directus Architecture — SSOT
6 min read Revision 1
ssotdirectusarchitectureagency-oscms
Directus Architecture — SSOT
Version: 1.0 Date: 2026-02-28 Status: Active (Production VPS) Nguồn: Audit Claude Code 2026-02-28
I. TỔNG QUAN
Directus là headless CMS trung tâm của Incomex Business OS, chạy trên VPS dưới tên Agency OS. Directus cung cấp REST + GraphQL API, quản lý structured data, phân quyền, và automation qua Flows — tất cả KHÔNG cần code.
II. INSTANCE INFO
| Thuộc tính | Giá trị |
|---|---|
| Image | directus/directus:11.5 |
| Version | 11.5.1 |
| Project Name | Agency OS |
| Project Descriptor | Multi-Tenant CMS Platform |
| Default Language | en-US |
| Public Registration | false |
| Extensions | Không có (empty dir) |
| Container | incomex-directus |
| Port | 8055 (internal only, qua Nginx) |
| Docker Network | docker_incomex (IP: 172.18.0.6) |
| Database | MySQL 8 (container incomex-mysql) |
| Health | ✅ OK |
| Started | 2026-02-27T14:02:40Z |
| Websockets | Enabled |
| Cache | Enabled |
| Rate Limiter | Enabled |
III. ENV VARS (keys only)
| Key | Mô tả |
|---|---|
| DB_CLIENT | mysql |
| DB_HOST | Container MySQL |
| DB_PORT | 3306 |
| DB_DATABASE | directus |
| DB_USER | *** |
| DB_PASSWORD | *** |
| ADMIN_EMAIL | *** |
| ADMIN_PASSWORD | *** |
| PUBLIC_URL | https://directus.incomexsaigoncorp.vn |
| FLOWS_ENV_ALLOW_LIST | AGENT_DATA_URL, AGENT_DATA_API_KEY |
| WEBSOCKETS_ENABLED | true |
| CACHE_ENABLED | true |
| RATE_LIMITER_ENABLED | true |
Thêm từ .env file: DIRECTUS_KEY, DIRECTUS_SECRET, DIRECTUS_ADMIN_TOKEN
IV. DOMAINS & ACCESS
| Domain | Vai trò | Auth |
|---|---|---|
| directus.incomexsaigoncorp.vn | Admin UI + full API | Bearer token |
| ops.incomexsaigoncorp.vn | AI Agent CRUD (filtered) | X-API-Key |
| vps.incomexsaigoncorp.vn/ops/ | AI Agent CRUD (legacy, deprecated) | X-API-Key |
OPS Proxy chỉ whitelist 3 collections: tasks, task_comments, ai_tasks. Mọi path khác trả 404/410.
V. ROLES & PERMISSIONS (Directus 11 Policies Model)
Roles (7)
| Role | Mô tả | Users | Policy |
|---|---|---|---|
| Administrator | Admin full access | 1 | Administrator |
| AI Agent | Tasks + comments only | 2 | AI Agent Policy |
| Agent | Draft + submit, không approve | 0 | Agent Policy |
| Editor | Review + approve, không publish | 0 | Editor Policy |
| Public (Restored Ghost) | Public read | 0 | Public Access |
| Antigravity Public | Public read | 0 | — |
| Public (Dedicated) | Public read | 0 | — |
Policies (6)
| Policy | Admin | App | Permissions | Scope |
|---|---|---|---|---|
| Administrator | ✅ | ✅ | 19 | directus_files, flows, knowledge_documents, os_* |
| AI Agent Policy | ❌ | ❌ | 25 | ai_tasks, checkpoint_*, task_comments, tasks |
| Agent Policy | ❌ | ✅ | 11 | agent_views, content_requests, feedbacks, knowledge_documents |
| Editor Policy | ❌ | ✅ | 8 | content_requests, knowledge_documents |
| Public Access | ❌ | ❌ | 45 | 36 collections (blocks, pages, posts, knowledge, agent_views...) |
| $t:public_label | ❌ | ❌ | 74 | 52 collections (mở rộng: tasks, checkpoints, AI discussions...) |
VI. DATA STATISTICS
| Metric | Value |
|---|---|
| MySQL tables | 118 |
| User collections | ~93 |
| System collections | 26 (directus_*) |
| Virtual/folder collections | 5 |
| Total rows (estimated) | ~14,000+ |
| Flows | 26 (22 active, 4 inactive) |
| Users | 11 |
| Knowledge documents | 117 |
| Task comments | 53 |
| Checkpoint types | 31 |
| Agent views | 22 |
Top 5 tables by rows: directus_activity (8,763), directus_revisions (4,400), directus_fields (941), directus_sessions (229), directus_relations (183).
VII. TÍCH HỢP
Directus ↔ Agent Data
- Sync qua Directus Flows (DOT prefix)
- Tasks + Comments: Directus → Agent Data (Directus là source of truth)
- Knowledge Documents: Agent Data → Directus (Agent Data là source of truth, sync DISABLED)
- Chi tiết: xem
knowledge/dev/ssot/directus/directus-flows.md
Directus ↔ Nuxt (Agency OS Frontend)
- Nuxt fetch data qua Directus SDK (@directus/sdk)
- REST API endpoints cho pages, posts, blocks, navigation
- Agency OS UI Kit: pre-built components render Directus data
- Composables: useKnowledge, useBlueprints, useContentRequests...
Directus ↔ AI Agents (OPS Proxy)
- GPT/Claude gọi qua ops.incomexsaigoncorp.vn
- Nginx filter + inject Directus AI Agent token
- Whitelist: tasks, task_comments, ai_tasks
- OpenAPI spec: ops.incomexsaigoncorp.vn/openapi.json
VIII. LIMITATIONS (v11.5.1)
| Limitation | Impact | Workaround |
|---|---|---|
| Không có isolated-vm | exec operations fail silently | Dùng condition-first pattern |
| Flows không read/update cùng collection với trigger | ai_tasks business logic không chạy trong Flow | Orchestrator script bên ngoài |
| Flows cần restart Directus sau khi tạo qua API | Flows mới không active ngay | docker restart incomex-directus |
IX. LIÊN KẾT SSOT
| Document | Path |
|---|---|
| Collections | knowledge/dev/ssot/directus/directus-collections.md |
| Flows | knowledge/dev/ssot/directus/directus-flows.md |
| Operating Rules | knowledge/dev/ssot/directus/directus-operating-rules.md |
| Data Sync Architecture | knowledge/dev/architecture/data-sync-architecture |
| OPS Proxy API Spec | knowledge/other/specs/ops-proxy-api-spec |
| VPS Architecture | knowledge/dev/ssot/vps/vps-architecture.md |