ERP-core/docs/01-DOC-GUIDE.md

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
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

# 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

# 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, mirroring the 10/11 SRS+ER / API-reference split), 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.