Appearance
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, skills | Khô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)
| Path | Boundary | Ghi chú |
|---|---|---|
platform-core/ | Platform domain SoT | Ownership identity/workspace/catalog/credential (logic + DB) |
platform-api/ | Platform HTTP APIs | Contract công khai mà Applications/SDK gọi (D-018) |
platform-sdk/ | Platform SDK | Client/helper mỏng; không phải hidden backend |
platform-file-service/ | File Service | Metadata DB SoT; bytes local/cloud; variant on-demand (FS_VARIANT_ROOT) |
platform-infra/ | Platform ops | Swarm stack dùng chung + config open-source (không secret) |
platform-ui/ | Shared UI kit | shadcn-like web kit (Next.js); Mobile-First; phù hợp WebView (D-020) |
platform-web/ | App Shell / portals | Shell end-user dùng chung; consume platform-ui; Flow 2 khi productize |
platform-mobile/ | RN WebView host | Shell native mỏng load platform-web / UI web Application (D-020) |
platform-admin/ | Admin sites | FE+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ị) | Boundary | Khi nào |
|---|---|---|
platform-chat/ | MINAP Chat | Sau 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 Integration | Khi thu tự động được phê duyệt (capability PROPOSED) |
platform-invoice/ | Shared Invoice Integration | Chỉ 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
- Mỗi nested repo sở hữu
.specify/,specs/,.minap/work-items/(+ optional.minap/discovery/),docs/, source và deploy assets riêng. - Không chia sẻ một Spec Kit
feature.jsongiữa các nested repos. - Platform Constitution chuẩn vẫn ở governance/docs SoT; mỗi nested repo giữ Spec Kit constitution đã sync dưới
.specify/memory/. - Thay đổi contract cross-repo dùng work item cha + work item con trên các repo bị ảnh hưởng.
- Không copy full
.cursor/kit vào mọi nested repo; mở multi-root kèmplatform-ai. - 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-coreURL remote được ghi khi tạo remotes; trước đó, git init trong nested path được phép cho bootstrap chỉ local.