# 01 · DOC-GUIDE — Documentation Map & Tracking Conventions > **Purpose:** This file explains the documentation system itself — what every doc is for, the order to read them, the single navigation rule, and the conventions for the two `PROGRESS.md` tracking files. It does **not** contain requirements or API detail; it tells you where those live and how to keep everything in sync. --- ## 1. The one navigation rule **All navigation starts at `00-CORE.md`.** `00-CORE.md` is the hub. Whatever the task, open it first and use its routing table (§7 there) to jump to the correct document. Do not work from memory or jump straight into a spec file — the hub exists so there is a single, consistent entry point for humans and for Claude. ``` ┌─────────────────┐ any task → │ 00-CORE.md │ (hub: structure, stack, setup, routing) └────────┬────────┘ ┌────────────┬───┴────────┬─────────────┬────────────┐ ▼ ▼ ▼ ▼ ▼ 10-BACKEND-P1 11-BACKEND-P1 20-FRONTEND 02-SECURITY 01-DOC-GUIDE (SRS+ER+arch) (API req/res) (flows+rules) (risks+ (this file) │ │ │ checklist) ▼ ▼ ▼ Backend/PROGRESS.md (record changes) Frontend/PROGRESS.md ``` 02-SECURITY is cross-cutting: consult it alongside the backend/frontend docs, and run its checklist before ticking any feature in a PROGRESS.md. --- ## 2. Document index | Doc | Level | Role | Read when | Who maintains | |---|---|---|---|---| | `00-CORE.md` | High | **Hub.** Structure, tech stack, runnable backend init, routing. | First — every task. | Claude + humans | | `01-DOC-GUIDE.md` | High | **This file.** Doc map, reading order, tracking conventions. | To understand the doc system. | Claude + humans | | `02-SECURITY.md` | High (cross-cutting) | **Security review aid:** accepted-risks register + per-feature checklist. | Before ticking any feature in a PROGRESS.md; during security review. | Claude + humans | | `10-BACKEND-PHASE1.md` | High | Backend spec: **full SRS**, **ER model / 38-entity list**, tech stack detail, layer/architecture rules. Schema is **authoritative** here. | Any backend model / business-rule / requirement work (Phase 1). | Claude + humans | | `11-BACKEND-PHASE1.md` | High | Backend **API reference**: every endpoint with complete request/response, error catalog, enums. | Any API contract / controller / client work (Phase 1). | Claude + humans | | `12-BACKEND-HRM.md` | High | HRM backend spec: SRS, ER model, HRM-specific architecture notes. Schema is **authoritative** here. | Any HRM model / business-rule / requirement work (Phase 2). | Claude + humans | | `13-BACKEND-HRM-API.md` | High | HRM **API reference**: every endpoint, error catalog additions, enums. | Any HRM API contract / controller work. | Claude + humans | | `12-GENERAL-LEDGER-INTEGRATION.md` | High | ERPCore ↔ external **General Ledger service**: connection/proxy contract, config, progress. GL's own endpoint contract lives in the GL service's own repo, not here. | Any work touching the GL proxy or a future internal GL caller. | Claude + humans | | `14-BACKEND-SALES-API.md` | High | Sales **API reference**: invoices, slips, free issues, reports, enums. | Any sales API contract / controller work. | Claude + humans | | `20-FRONTEND.md` | High | Frontend **user-flows**, architecture rules to follow, **validation posture**. | Any frontend work (Phase 1). | Claude + humans | | `21-FRONTEND-HRM.md` | High | HRM frontend **user-flows**, screens, validation specifics. | Any HRM frontend work. | Claude + humans | | `30-BACKEND-PHASE2.md` | High | Manufacturing (Production Lines) backend: SRS, ER model, status machines, stock/costing integration, **and** the full API contract — model and API in one doc, unlike Phase 1. Schema is **authoritative** here. | Any manufacturing model / rule / API work. | Claude + humans | | `21-FRONTEND-PHASE2.md` | High | Manufacturing frontend **user-flows**: template canvas builder, run board, run execution screens. | Any manufacturing frontend work. | Claude + humans | | `21-GENERAL-LEDGER-FRONTEND.md` | High | **Ledgers** sidebar section: statutory-format report screens + PDF download, Cash/Bank Accounts (list/create; edit gap explained). Extends `20-FRONTEND.md` rather than duplicating it. | Any work on `app/dashboard/ledgers/*`. | Claude + humans | | `Backend/PROGRESS.md` | Low | Backend **change checklist**, git-shared. | After making backend changes. | **Claude** | | `Frontend/PROGRESS.md` | Low | Frontend **change checklist**, git-shared. | After making frontend changes. | **Claude** | Numbering convention: `0x` = high-level hub/guide/cross-cutting, `1x` = backend, `2x` = frontend. Numbers sort in read order in any file browser. > **Known deviation:** `30-BACKEND-PHASE2.md` is a backend doc numbered `3x` rather than continuing the `1x` decade, and it merges the model and the API contract into one file instead of the `10`/`11` split. Left as-is — it is already the established reference for the manufacturing phase and renumbering it would invalidate every existing cross-reference. New backend phases should return to the `1x` convention. --- ## 3. Reading order (first time) 1. **`00-CORE.md`** — understand the project, structure, stack, and how to stand up the backend. 2. **`01-DOC-GUIDE.md`** (this file) — understand the doc system and tracking. 3. Then, per task, jump via the hub to `10-`, `11-`, or `20-`. 4. **`02-SECURITY.md`** — read the accepted-risks register once, then use its checklists during development. You do not need to read `10/11/20` end-to-end before starting; open the section relevant to your task via the hub. --- ## 4. Which doc answers which question | Question | Answer lives in | |---|---| | "What is the business rule for X?" / "What entity/field is this?" | `10-BACKEND-PHASE1.md` | | "What does endpoint Y accept and return?" / "What's the error code?" | `11-BACKEND-PHASE1.md` | | "How does the user move through the UI?" / "What do I validate on the client vs server?" | `20-FRONTEND.md` | | "How do I set up / run the project?" | `00-CORE.md` | | "What security risks apply to this feature?" / "What must I check before shipping it?" | `02-SECURITY.md` | | "Is this exposure a bug or an accepted Phase-1 risk?" | `02-SECURITY.md` (Part A register) | | "Where do I record what I changed?" | `Backend/PROGRESS.md` or `Frontend/PROGRESS.md` (this file, §6) | If a question spans backend + frontend (e.g. a new feature), read the backend spec/API first (the contract), then the frontend doc (how the UI consumes it). For any feature that mutates data, also run its `02-SECURITY.md` checklist. --- ## 5. Maintenance rules (single source of truth) - **One source of truth per topic.** Requirements live only in `10-`; API contracts live only in `11-`; frontend rules live only in `20-`. Do not copy content between docs — link instead. - **Edit in place.** When a requirement or endpoint changes, update it where it lives. Never fork a second copy. - **Contract before consumer.** Change the backend spec/API doc first, then update the frontend doc and code to match. - **Keep the hub thin.** `00-CORE.md` routes and sets up; it must not accumulate requirement/API detail. - **Every material change updates a `PROGRESS.md`** (see §6). Docs and trackers move together in the same commit as the code. --- ## 6. Tracking convention — `PROGRESS.md` Two low-level checklists record what has actually been built. They live **inside** each project so they travel with code across branches and are diff-visible in git: - `Backend/PROGRESS.md` - `Frontend/PROGRESS.md` ### 6.1 Rules - **Claude maintains these.** On every change to a side, update that side's `PROGRESS.md` in the **same commit** as the code. - Use checkboxes: `- [ ]` not started · `- [~]` in progress · `- [x]` done. - Each entry is a concrete, verifiable unit of work (an endpoint, an entity + its configuration, a service method, a screen, a validation rule) — not vague ("did stuff"). - Group by module/area so the file mirrors the spec structure. - When ticking `- [x]`, append a short note: what was done + any deviation from the spec (and why). - Never delete history; move completed items under a **Done** section if the active list gets long. - If a change alters a spec doc (`10/11/20`), reference it: `(updates 11-BACKEND-PHASE1 §5.4)`. ### 6.2 Backend `PROGRESS.md` starter template ```markdown # Backend — PROGRESS (Phase 1: Inventory & Supply Chain) Legend: [ ] not started · [~] in progress · [x] done Spec: docs/10-BACKEND-PHASE1.md (model) · docs/11-BACKEND-PHASE1.md (API) ## 0. Bootstrap - [ ] Solution + Web API project (net10.0), packages restored - [ ] Folder structure per 00-CORE §5.3 - [ ] ErpDbContext + Npgsql wired; InitialCreate migration applied - [ ] Serilog, JWT, Swagger, HealthChecks, ProblemDetails in Program.cs - [ ] UnitOfWork + generic repository base - [ ] ICurrentUser (audit stamp from token) ## 1. Master Data - [ ] Item: entity + config + enum(s) - [ ] Item: repository + service + controller (CRUD, DTOs) - [ ] UOM + conversions - [ ] Category (hierarchy) - [ ] Vendor - [ ] Warehouse + Bin - [ ] Item reorder settings ## 2. Procurement - [ ] Requisition (+ lines) - [ ] RFQ + quotations + comparison - [ ] Purchase Order (create, edit-while-open, auto-approve, cancel) - [ ] Purchase Return ## 3. Goods Receipt - [ ] GRN (create against PO / direct) - [ ] GRN confirm → FIFO layer + ledger + PO qtyReceived - [ ] Inspection hold release/reject ## 4. Stock Core - [ ] StockLayer + StockLedger entities/config - [ ] FifoCostingService (consume oldest-first, valuation) - [ ] Stock enquiry (onHand/available/onHold/inTransit) - [ ] Ledger query · Valuation query ## 5. Stock Transactions - [ ] Transfer (create → dispatch → receive, in-transit, cost-preserving) - [ ] Adjustment (auto-post, reason code) - [ ] Count (cycle/full → variance → post) - [ ] Reorder alerts ## 6. Cross-cutting - [ ] ProblemDetails error catalog + domain exceptions - [ ] Audit log on mutations - [ ] Auth (simple in-app login → JWT) - [ ] Document numbering sequences ## Done ``` ### 6.3 Frontend `PROGRESS.md` starter template ```markdown # Frontend — PROGRESS (Phase 1: Inventory & Supply Chain) Legend: [ ] not started · [~] in progress · [x] done Spec: docs/20-FRONTEND.md (flows + rules) · docs/11-BACKEND-PHASE1.md (API contract) ## 0. Foundation - [ ] API base URL env wired (NEXT_PUBLIC_API_BASE_URL) - [ ] Typed API client / fetch wrapper + auth token handling - [ ] Shared types mirroring API DTOs - [ ] Client-side validation helpers (dependency-free) ## 1. Screens / flows (per 20-FRONTEND user-flows) - [ ] Login - [ ] Items (list + create/edit) - [ ] Vendors · Warehouses/Bins - [ ] Requisition → PO flow - [ ] GRN (receive + hold handling) - [ ] Stock: enquiry · transfer · adjustment · count · reorder ## 2. Validation posture (client for UX; server authoritative) - [ ] Client format/required/range checks on forms - [ ] Surface server ProblemDetails errors (incl. domain codes) - [ ] Never assume stock/availability rules client-side ## Done ``` --- ## 7. Adding future docs When later phases arrive (Sales & CRM, Manufacturing, QC/QA, Accounting), follow the same scheme HRM (Phase 2) established: - Backend spec/API for a phase → new `1x-` files continuing the backend decade (e.g. HRM used `12-BACKEND-HRM.md` + `13-BACKEND-HRM-API.md`; sales now uses `14-BACKEND-SALES-API.md` alongside the existing phase docs), linked from the hub. - Frontend additions → extend `20-FRONTEND.md` or add `2x-` files (e.g. HRM used `21-FRONTEND-HRM.md`). - Always register the new doc in `00-CORE.md` routing (§7) and in this index (§2). --- *End of 01-DOC-GUIDE.md. Return to `00-CORE.md` to route to your task.*