Codebase Doc

/codebase-doc — Codebase Documentation Architect

Tổng quan

Skill có 2 phase độc lập:

Phase 1 — SCAN:  /codebase-doc --scan
  └─ Quét routes → cập nhật docs/ROUTE_LIST.md (registry trung tâm)

Phase 2 — GEN:   /codebase-doc --gen --module <tên> [options]
  └─ Đọc ROUTE_LIST.md → gen/update docs/modules/{tên}.md

Registry trung tâm: docs/ROUTE_LIST.md Module docs: docs/modules/{module}.md

Cấu trúc output thực tế

docs/
├── ROUTE_LIST.md              ← Central registry
└── modules/
    ├── alert.md
    ├── autoscaling.md
    ├── backup.md
    ├── cloud-advisor.md
    ├── custom-image.md
    ├── ddos.md
    ├── edge-gateway.md
    ├── floating-ip.md
    ├── global-search.md
    ├── iam.md
    ├── load-balancer.md
    ├── lbaas-v2.md
    ├── networks.md
    ├── nic.md
    ├── osp-native-backup.md
    ├── recent-tasks.md
    ├── s3.md
    ├── schedule.md
    ├── security-groups.md
    ├── snapshot-schedule.md
    ├── storage.md
    ├── vm.md
    ├── vm-group.md
    ├── vpnaas.md
    └── ...

Phase 1: SCAN — /codebase-doc --scan

Mục đích

Quét toàn bộ route files, cập nhật docs/ROUTE_LIST.md. Không gen module doc nào.

Format docs/ROUTE_LIST.md

Tuân thủ chính xác format hiện tại:

# Route List — Chi tiết tất cả routes

**Service:** `portal-api-svc-iaas-vmw`
**Total:** {N} routes / {M} modules
**Legend:** ✅ Documented đầy đủ | 🟡 Partial | ❌ Chưa có docs

---

## V1 — Main API (/api/v1/)

### {STATUS} `v1/{module}` — {N} routes | Docs: {ID range} ({file}.md)

| Method | Path            |
| ------ | --------------- |
| `GET`  | `/some/path`    |
| `POST` | `/another/path` |

DOC_STATUS:

• ✅ — documented đầy đủ, tất cả flows có diagram
• 🟡 — partial, có doc nhưng còn thiếu flows
• ❌ — chưa có docs

Docs field:

• Có: Docs: FIP-01→FIP-11 (floating-ip.md)
• Partial: Docs: AL-01→AL-06 (partial)
• Không: Docs: —

Thực hiện

Bước 1 — Tìm route files

Đọc: router registration file (__init__.py / router.go / index.ts)
Với mỗi route file:
  - Ghi FULL PATH tuyệt đối từ project root:
    ✅ portal-api-svc-iaas-vmw/service/api/v1/floating_ips/blueprint.py
    ❌ service/api/v1/floating_ips  ← thiếu prefix
  - Đọc file: method, path, handler, IAM decorator nếu có
  - Group theo blueprint/module name
  - Đếm routes

Bước 2 — Nhóm theo version

/api/v1/           → ## V1 — Main API
/api/v2/           → ## V2 — API v2
/api/v1/api_internal/ → ## V1 Internal

Bước 3 — Check doc status

Đọc docs/modules/ → biết module nào đã có
So sánh Flow Inventory trong file đó với routes scan được:
  Không có file       → ❌
  File có nhưng FLOW_PROGRESS chưa N/N → 🟡 partial
  FLOW_PROGRESS = N/N → ✅

Bước 4 — Cập nhật ROUTE_LIST.md

ROUTE_LIST.md đã tồn tại:
  → Chỉ thêm routes MỚI, không xóa rows cũ
  → Update DOC_STATUS cho modules có doc mới
  → Cập nhật Total count header

Chưa có: tạo mới

Output sau scan:

Scan hoàn tất:
  Total: 1519 routes / 148 modules
  ✅ 18 modules documented
  🟡 9 modules partial
  ❌ 121 modules chưa có docs

  Ưu tiên cao (route count):
    ❌ v1/organization     — 67 routes
    ❌ v1/public_api/common — 55 routes
    ❌ v1/contract         — 28 routes

  Chạy:
    /codebase-doc --gen --module organization
    /codebase-doc --gen --module contract

Phase 2: GEN — /codebase-doc --gen [options]

Options

--module <tên>

Bước 1 — Đọc ROUTE_LIST.md, không scan lại source

Tìm section tương ứng trong ROUTE_LIST.md
Lấy: danh sách routes (method + path)
Lấy: file paths đã ghi từ lần scan

CHỈ đọc files có trong ROUTE_LIST.md section đó.
Không đọc files module khác.
Không scan lại toàn project.

Bước 2 — Đọc file hiện có nếu đã tồn tại

Nếu docs/modules/{tên}.md đã có:
  - Đọc Flow Inventory để biết flows nào đã có diagram
  - FLOW_PROGRESS comment để biết tiến độ
  - Append/update phần còn thiếu, KHÔNG xóa content cũ

Nếu chưa có: tạo mới

Bước 3 — Completion Gate

Công bố trước khi vẽ:
  "Module {tên}: {N} flows
   Có diagram (async/complex): {list IDs}
   Skip diagram (GET read-only): {list IDs}
   Bắt đầu: 0/{N_async}"

Cập nhật FLOW_PROGRESS sau MỖI flow — không batch.
KHÔNG dừng cho đến FLOW_PROGRESS = N/N.

Nếu context limit sắp hết:
  Ghi <!-- INCOMPLETE: còn FIP-08, FIP-09 -->
  Để --flows-remaining tiếp tục chính xác.

Anti-shortcuts:

❌ "Tương tự FIP-01, xem FIP-01"  → phải vẽ thật
❌ "Còn lại theo pattern tương tự" → phải vẽ từng cái
❌ Gộp 2 flows vào 1 diagram       → mỗi flow 1 diagram riêng

Format docs/modules/{tên}.md

Format chuẩn — tuân thủ chính xác như floating-ip.md và alert.md:

# Module: {Tên hiển thị}

## Overview

{Mô tả module làm gì, business context, loại operations}
{Liệt kê sub-features nếu có: DNAT, SNAT, NO-SNAT...}

**{External system name}:** {Tên cụ thể} ({internal/external}, via `{ENV_VAR}`)
**{Async info}:** Celery task `{task_name}` cho {operation}, `{task2}` cho {op2}

## Files

| File                                                           | Mục đích             |
| -------------------------------------------------------------- | -------------------- |
| `portal-api-svc-iaas-vmw/service/api/v1/{module}/blueprint.py` | Route definitions    |
| `portal-api-svc-iaas-vmw/service/managers/{Manager}.py`        | Business logic       |
| `portal-celery/tasks/{task}.py`                                | Celery: {mô tả task} |

## Flow Inventory

| Flow ID  | Endpoint                                 | Method | Description  |
| -------- | ---------------------------------------- | ------ | ------------ |
| {PRE}-01 | `/api/v1/vmware/vpc/{vpcId}/{path}`      | POST   | {Mô tả ngắn} |
| {PRE}-02 | `/api/v1/vmware/vpc/{vpcId}/{path}`      | GET    | {Mô tả ngắn} |
| {PRE}-03 | `/api/v1/vmware/vpc/{vpcId}/{path}/{id}` | PUT    | {Mô tả ngắn} |
| {PRE}-04 | `/api/v1/vmware/vpc/{vpcId}/{path}/{id}` | DELETE | {Mô tả ngắn} |

<!-- FLOW_PROGRESS: 0/{N} -->

## Sequence Diagrams

### Flow {PRE}-01: {Tên flow}

```mermaid
sequenceDiagram
    title {PRE}-01 — {Tên flow đầy đủ}

    actor User
    participant API as VMware IaaS API :5020
    participant DB as MySQL
    [participant Redis as Redis]          ← chỉ thêm nếu có cache
    [participant Celery as Celery Worker] ← chỉ thêm nếu có async
    [participant IAM as Keycloak IAM]     ← chỉ thêm nếu có IAM call
    [participant {Ext} as {External}]     ← tên system cụ thể

    User->>API: {METHOD} {full path}\n{{request body nếu POST/PUT}}
    Note over API: @{iam_decorator}({Actions.Resource.action})\n@{other_decorators}

    [API->>IAM: iam_validate → check {permission}]
    [IAM-->>API: 200 OK]

    [API->>DB: {lookup/validate query}]
    [DB-->>API: {kết quả}]

    alt {Error condition 1}
        API-->>User: {status} {ERROR_CODE hoặc message}
    else {Error condition 2}
        API-->>User: {status} {ERROR_CODE}
    end

    [sync GET: trả về luôn, không cần Celery section]
    API-->>User: 200 OK {{response}}

    [async: dispatch Celery rồi return 200/202, Celery xử lý tiếp]
    API->>DB: INSERT/UPDATE {table} (status=PENDING/CREATING)
    API->>Celery: send_task({task_name}, kwargs={{...}})
    Note over Celery: Async — {task_file}::{task_function}\n{mô tả ngắn task làm gì}
    API-->>User: 200 OK {{status, message}} hoặc 202 Accepted

    Celery->>{Ext}: {External API call}
    {Ext}-->>Celery: {response}

    alt SUCCESS
        Celery->>DB: UPDATE {table} SET status=ACTIVE
        [Celery->>DB: UPDATE quota_usage]
    else ERROR / Timeout
        Celery->>DB: UPDATE {table} SET status=ERROR
        [Celery->>DB: Rollback quota nếu applicable]
    end
```

File: {full/path/blueprint.py}::{handler_function}() Task: {full/path/tasks.py}::{task_function} | Queue: {queue_name} Gotchas:

• {Điều gì cần chú ý — edge case, limitation, gotcha thực tế}

[Repeat cho mỗi flow]

Known Issues & Gotchas

---

### Rules bắt buộc khi viết sequence diagrams

**1 — Participants: chỉ thêm những gì thực sự tham gia**

actor User → luôn có participant API → luôn có, ghi rõ port: "VMware IaaS API :5020" participant DB → thêm nếu có DB query participant Redis → thêm nếu có cache read/write participant Celery → thêm nếu có async task participant IAM → thêm nếu có IAM call riêng (không phải chỉ decorator) participant {ExtSys} → tên cụ thể: "VMware VCD", "OpenStack", "Monasca / FMon", "Billing Service", "Veeam", "Jira", "Firebase"

**2 — Note over API: ghi decorators thực tế**

```mermaid
Note over API: @iam_validate(Actions.Ip.connect)\n@check_billing_budget()

Đọc blueprint.py để lấy decorator names thực tế, không đoán.

3 — alt/else blocks: đọc code để lấy error conditions thực tế

alt No edge gateway found
    API-->>User: 400 EDGE_GATEWAY_NOT_EXIST
else Multiple edge gateways
    API-->>User: 400 EDGE_GATEWAY_SIZE_INVALID
end

Không dùng generic "Error occurred" — phải là error code/message thực từ code.

4 — Phân biệt sync vs async

Sync (GET, validate):

API->>DB: SELECT ...
DB-->>API: data
API-->>User: 200 OK {data}

Async (POST/PUT/DELETE có Celery):

API->>DB: INSERT resource (status=PENDING)
API->>Celery: send_task(task_name, kwargs={...})
Note over Celery: Async — tasks/file.py::task_function
API-->>User: 200 OK {status: true}

Celery->>ExternalSys: API call
ExternalSys-->>Celery: result
Celery->>DB: UPDATE resource (status=ACTIVE)

5 — Ghi rõ task name và file thực tế

Note over Celery: wf_allocate_pool_v2 execution:

hoặc

Note over Celery: Async — portal-celery/tasks/vm.py::create_vm_task

6 — Flow ID prefix theo module

FIP → Floating IP
AL  → Alert
VM  → VM / Compute
SG  → Security Group
NW  → Network
STO → Storage
BK  → Backup
LB  → Load Balancer
VPN → VPNaaS
IAM → IAM
ORG → Organization
ANN → Annex
CTR → Contract
SCL → Scaling
SCH → Schedule
...

7 — Flows nào cần diagram vs không cần

Cần diagram:

• POST/PUT/DELETE có Celery async
• POST/PUT/DELETE có external API call (VCD, OpenStack, Monasca...)
• GET có complex logic (multiple branches, quota check, IAM validation)
• GET có external call

Có thể skip diagram (chỉ ghi vào Flow Inventory):

• GET đơn giản đọc DB và trả về
• Validation endpoints (GET check-name, GET validate-*)
• Reference data endpoints (GET list alarm-metrics, GET list-severity...)

--api <IDs>

Gen doc cho 1-2 flows cụ thể.

/codebase-doc --gen --api FIP-01,FIP-06

1. Đọc ROUTE_LIST.md → lấy file path của FIP-01, FIP-06
2. Đọc đúng 2 file đó
3. Nếu docs/modules/floating-ip.md đã tồn tại: append flow vào section "Sequence Diagrams", update Flow Inventory table
4. Cập nhật ROUTE_LIST.md: DOC_STATUS → 🟡 partial (nếu chưa đủ) hoặc ✅

--update-mr

Gen release note để paste vào MR description.

/codebase-doc --gen --update-mr

1. git diff main..HEAD --name-only → files thay đổi
2. Map files → Flow IDs trong ROUTE_LIST.md
3. git log --oneline main..HEAD → commits
4. Đọc nội dung files thay đổi để hiểu change
5. Output:

## Release Note — [branch] — [date]

### Summary

[1-2 câu mô tả MR làm gì]

### APIs Changed

| Module      | Flow ID | Method | Path                                   | Change                          |
| ----------- | ------- | ------ | -------------------------------------- | ------------------------------- |
| floating-ip | FIP-01  | POST   | /vpc/{id}/floating-ips/allocate-pool   | Fix quota drift khi Celery fail |
| vm          | VM-05   | PUT    | /vpc/{id}/compute/instance/{id}/resize | Thêm concurrent lock            |

### Breaking Changes

- [Nếu có]
- Không có breaking changes

### Celery Tasks Changed

- `wf_allocate_pool_v2` — Thêm rollback khi VCD timeout

### Migration Required

- [Nếu có Alembic migration]
- Không cần migration

### Commits

- a1b2c3d fix: quota drift on allocate pool
- b2c3d4e feat: distributed lock for resize

### How to Test

1. [Step cụ thể]
2. [Step cụ thể]

### Checklist

- [ ] Unit tests pass
- [ ] Related docs updated: docs/modules/floating-ip.md
- [ ] ROUTE_LIST.md DOC_STATUS updated

Sau khi gen: update ROUTE_LIST.md — files bị thay đổi → DOC_STATUS = 🔄 stale (nếu có doc cũ).

--flows-remaining

Tiếp tục sau context limit.

/codebase-doc --gen --module floating-ip --flows-remaining

1. Đọc docs/modules/floating-ip.md
2. Tìm <!-- INCOMPLETE: còn FIP-08, FIP-09 -->
3. Đọc ROUTE_LIST.md → lấy file paths của FIP-08, FIP-09
4. Đọc đúng các files đó
5. Append flows còn thiếu, xóa INCOMPLETE comment
6. Cập nhật FLOW_PROGRESS
7. Update ROUTE_LIST.md DOC_STATUS

--codex (opt-in)

Chỉ chạy khi có flag này. Không bao giờ tự động.

/codebase-doc --gen --module floating-ip --codex

Output thêm .codex/modules/floating-ip.md:

# MODULE: floating-ip

# Agent: load file này khi task liên quan Floating IP / Public IP

ROUTE_FILES:
portal-api-svc-iaas-vmw/service/api/v1/floating_ips/blueprint.py
MANAGER_FILES:
portal-api-svc-iaas-vmw/service/managers/floating_ip_manager/FloatingIpManager.py
portal-api-svc-iaas-vmw/service/managers/NatRuleManager.py
TASK_FILES:
portal-celery/tasks/wf_allocate_pool_v2.py

FLOWS: FIP-01 POST allocate-pool | FIP-02 GET list | FIP-03 POST no-snat | FIP-06 POST payg/create

EXTERNAL_CALLS:
VCD: allocate IP from edge gateway pool
OpenStack: get_network_by_router, allocate floating IP

DB_TABLES: floating_ip (rw), nat_rule (rw), quota_usage (rw)
REDIS_KEYS: quota:{vpc_id} TTL=300

KNOWN_BUGS:
quota_drift | Celery fail sau allocate → quota không rollback
multi_egw_500 | VPC có >1 EGW → raise Exception thay vì 400
port_race | Public port uniqueness check không có DB lock

Workflow theo team

Lead / DevOps — lần đầu setup

/codebase-doc --scan

git add docs/ROUTE_LIST.md
git commit -m "chore: initial route registry scan — 1519 routes / 148 modules"

Team gen doc module của mình

# network-team gen floating-ip
/codebase-doc --gen --module floating-ip

git add docs/modules/floating-ip.md docs/ROUTE_LIST.md
git commit -m "docs: floating-ip module — FIP-01 to FIP-11"

# compute-team gen vm (độc lập, cùng lúc)
/codebase-doc --gen --module vm

git add docs/modules/vm.md docs/ROUTE_LIST.md
git commit -m "docs: vm module — VM-01 to VM-34"

Khi push MR

/codebase-doc --gen --update-mr
# Paste release note vào MR description

# Nếu MR thay đổi floating-ip module:
/codebase-doc --gen --module floating-ip
git add docs/modules/floating-ip.md docs/ROUTE_LIST.md
git commit -m "docs: update floating-ip doc after quota fix"

Tiếp tục sau context limit

/codebase-doc --gen --module organization --flows-remaining
# Claude đọc INCOMPLETE comment → vẽ tiếp đúng flows còn thiếu

Output Checklist

Sau --scan

□ ROUTE_LIST.md đúng format: header, legend, sections V1/V2/Internal
□ Mỗi module có: status, route count, docs reference
□ Mỗi route có: method + path (full path từ blueprint)
□ Total count khớp với số routes thực tế
□ DOC_STATUS đúng dựa trên FLOW_PROGRESS trong module files

Sau --gen --module

□ docs/modules/{tên}.md có đúng 5 sections: Overview, Files, Flow Inventory, Sequence Diagrams, Known Issues
□ Overview mô tả đúng business context + external systems + async info
□ Files table có FULL PATH của blueprint + manager + task files
□ Flow Inventory có đủ tất cả routes của module (kể cả GET read-only)
□ FLOW_PROGRESS = N/N (không còn INCOMPLETE comment)
□ Mỗi diagram async có: Note over Celery, alt SUCCESS/ERROR, status codes
□ Decorators ghi đúng từ code (@iam_validate, @check_billing_budget...)
□ Error codes là codes thực từ code, không phải generic
□ Known Issues ghi issues thực, không phải checklist chung chung
□ ROUTE_LIST.md đã update DOC_STATUS cho module

Sau --update-mr

□ Release note có: summary, APIs Changed table với Flow IDs, commits
□ APIs Changed map đúng file thay đổi → Flow ID
□ ROUTE_LIST.md mark stale cho routes bị ảnh hưởng

Anti-patterns

• ❌ Đọc files ngoài ROUTE_LIST.md khi --gen (không tự scan thêm)
• ❌ Gen module khác khi đang --gen --module X
• ❌ "Tương tự flow Y" — mỗi flow phải có diagram riêng
• ❌ Note over API để trống hoặc generic — phải ghi decorator thực
• ❌ alt Error occurred — phải là error code/condition thực từ code
• ❌ Ghi .codex/ khi không có --codex flag
• ❌ Để FLOW_PROGRESS không cập nhật sau mỗi flow
• ❌ Gen HTML (bỏ hoàn toàn)
• ❌ Module doc thiếu Known Issues section — phải có, kể cả khi chỉ có INFO
• ❌ Files table dùng relative path — phải là full path từ project root