# 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
<!-- move [x] items here with date + note if the active list grows -->
```

### 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
<!-- move [x] items here with date + note if the active list grows -->
```

---

## 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.*
