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-PHASE1  11-BACKEND-PHASE1   20-FRONTEND       01-DOC-GUIDE
 (SRS+ER+arch)      (API req/res)       (flows+rules)     (this file)
        │                │                 │
        ▼                ▼                 ▼
 Backend/PROGRESS.md   (record changes)   Frontend/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
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.	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.	Claude + humans
20-FRONTEND.md	High	Frontend user-flows, architecture rules to follow, validation posture.	Any frontend work.	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, 1x = backend, 2x = frontend. Numbers sort in read order in any file browser.

---

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

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
"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).

---

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, HRM), follow the same scheme:

• Backend spec/API for a phase → new 1x- files (e.g. 30-BACKEND-PHASE2.md), linked from the hub.
• Frontend additions → extend 20-FRONTEND.md or add 2x- files.
• 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.