Skip to content

Topology Workspace — Nested Independent Repositories ​

Version: 1.1
Date: 2026-11-20
Status: DECIDED

Model: Một cây workspace MINAP local; nhiều git remote độc lập.

Ý định ​

  • Owner / Orchestrator làm việc dưới một path local duy nhất: …/MINAP/.
  • Các repo platform-common và mỗi Application là repository git hoàn toàn tách biệt.
  • Developer người chỉ clone repo họ cần; không bắt buộc có hub.
  • platform-ai = shared AI kit (agents/rules/skills/templates). Artifact phát sinh theo feature nằm ở repo đích.

Bố cục ​

text
MINAP/                          # local workspace root (multi-root Cursor)
├── platform-ai/                # SHARED AI kit: .cursor/ + .minap/templates|schemas
├── platform-docs/              # SoT docs (VitePress) + framework
├── platform-core/              # Account / Workspace / catalog / credentials ownership
├── platform-api/               # Platform HTTP API surface + OpenAPI contracts
├── platform-sdk/               # Client SDK packages (consumes Platform API)
├── platform-file/              # File Service (metadata + object storage)
├── platform-infra/             # Shared ops: Swarm + Nginx/Traefik/Keycloak/Infisical/MinIO
├── platform-ui/                # Shared Mobile-First UI kit (D-020)
├── platform-web/               # App Shell / portals (stub; Flow 2 khi productize)
├── platform-mobile/            # RN WebView host (stub; D-020)
├── platform-admin/             # Admin operator (stub; Flow 1)
├── app-salon-manager/          # Application remotes (pilot names may differ from A/B/C)
├── app-rental-manager/
└── app-study/

AI kit vs artifact theo repo ​

Shared (platform-ai)Theo repo đích (vd. platform-ui)
.cursor/agents, rules, skillsKhông duplicate full kit (multi-root với platform-ai)
.minap/templates/ (discovery + orchestrator prompts).minap/discovery/<slug>/ (working fill)
.minap/schemas/, kit framework.yaml defaults.minap/work-items/, repo framework.yaml pin
—.specify/, specs/<feature>/

Folder .cursor / .claude rỗng ​

Cursor (và tooling liên quan Claude) thường tạo thư mục marker trên mỗi folder trong multi-root workspace. Nếu không có agents/rules thì folder rỗng — không phải SoT, không commit. Xóa an toàn; kit dùng chung chỉ ở platform-ai/.cursor/.

Path platform-common (stub hiện tại) ​

PathBoundaryGhi chú
platform-core/Platform domain SoTOwnership identity/workspace/catalog/credential (logic + DB)
platform-api/Platform HTTP APIsContract công khai mà Applications/SDK gọi (D-018)
platform-sdk/Platform SDKClient/helper mỏng; không phải hidden backend
platform-file-service/File ServiceMetadata DB SoT; bytes local/cloud; variant on-demand (FS_VARIANT_ROOT)
platform-infra/Platform opsSwarm stack dùng chung + config open-source (không secret)
platform-ui/Shared UI kitshadcn-like web kit (Next.js); Mobile-First; phù hợp WebView (D-020)
platform-web/App Shell / portalsShell end-user dùng chung; consume platform-ui; Flow 2 khi productize
platform-mobile/RN WebView hostShell native mỏng load platform-web / UI web Application (D-020)
platform-admin/Admin sitesFE+BE operator; Flow 1; domain SoT first-party (không SDK / không platform-api publish)

Path platform-common (dành sẵn khi được ủy quyền — không tạo remote sớm) ​

Path (tên khuyến nghị)BoundaryKhi nào
platform-chat/MINAP ChatSau khi lõi Salon được xác nhận; Chat không bắt buộc cho lát cắt dọc đầu
platform-payment/Shared Payment IntegrationKhi thu tự động được phê duyệt (capability PROPOSED)
platform-invoice/Shared Invoice IntegrationChỉ khi pilot cần (capability PROPOSED)

Config runtime open-source dùng chung nằm trong platform-infra/ (Nginx, Traefik, Keycloak, Infisical, MinIO). Deploy riêng từng service vẫn ở deploy/ của repo sản phẩm. Secrets nằm Infisical (D-016), không commit vào git.

Hub .gitignore bỏ qua nội dung nested checkout ngoại trừ README stub của mỗi path.

Quy tắc ​

  1. Mỗi nested repo sở hữu .specify/, specs/, .minap/work-items/ (+ optional .minap/discovery/), docs/, source và deploy assets riêng.
  2. Không chia sẻ một Spec Kit feature.json giữa các nested repos.
  3. Platform Constitution chuẩn vẫn ở governance/docs SoT; mỗi nested repo giữ Spec Kit constitution đã sync dưới .specify/memory/.
  4. Thay đổi contract cross-repo dùng work item cha + work item con trên các repo bị ảnh hưởng.
  5. Không copy full .cursor/ kit vào mọi nested repo; mở multi-root kèm platform-ai.
  6. Source nested không bao giờ được commit nhầm vào remote của repo khác.

Bootstrap nested checkout ​

bash
# Example: Platform Core
rm -f platform-core/README.md
rmdir platform-core 2>/dev/null || true
git clone <PLATFORM_DOMAIN_REMOTE_URL> platform-core

URL remote được ghi khi tạo remotes; trước đó, git init trong nested path được phép cho bootstrap chỉ local.

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English