DemozPay — Documentation Audit & Cleanup Plan

Author posture: Principal Technical Writer + Staff Architect. Snapshot: 2026-05-31. Method: enumerated all 143 markdown files; six parallel Explore agents read clusters; characterisations cited file:line. Code is the source of truth — where docs and code conflict, the code wins and the gap is named.

Why this exists: the repo has 143 .md files. A new developer cannot read them all and cannot tell which to trust. This document audits every one, names the duplication, designs a clean structure, and proposes a cleanup plan.

---

Table of contents

1. Headline findings
2. Phase 1 — Documentation inventory
3. Phase 2 — Duplication matrix
4. Phase 3 — New documentation structure
5. Phase 4 — New-developer onboarding review
6. Phase 5 — Document quality scores
7. Phase 6 — Cleanup execution plan
8. Single source of truth — final assignments

---

1. Headline findings

• 143 markdown files in the repo. After cleanup the target is ~70 active files plus an archive.
• The repo has at least 8 documents that claim to describe the system's status / roadmap — SYSTEM_GAP.md, SYSTEM_GAP_ACTION_PLAN.md, 90_DAY_EXECUTION_PLAN.md, GO_LIVE_BLOCKERS.md, PRODUCTION_READINESS.md, REAL_SYSTEM_STATE.md, SYSTEM_NOT_IMPLEMENTED.md, DOMAIN_COMPLETENESS_MATRIX.md — plus the three new audits I wrote (CURRENT_STATE_AUDIT.md, API_INVENTORY_FRESH.md, ROADMAP_REALITY_CHECK.md). This is the single biggest source of confusion.
• README.md + CLAUDE.md + PROJECT_STRUCTURE.md triple-document the same stack, layout, and commands. A new reader doesn't know which to start with.
• 11 .md files under dist/ are accidentally committed (.gitignore:4 already ignores dist/). Remove via git rm --cached.
• 20+ Docusaurus template files under apps/docs-web/ are 95% boilerplate (tutorial-basics/*, tutorial-extras/*, the 3 example blog posts, half the portals/*.md). If we wire docs-web up for real, these get wiped first.
• Onboarding is split between two competing trees — docs/onboarding/01-09-*.md (older, partially stale) and the newer DEVELOPER_GUIDE.md + DOMAIN_KNOWLEDGE_BASE.md. A new dev opens both, reads contradictions, leaves confused.
• README.md still says Payroll + Equb are Planned (line 14, 19). Both are Live (backend) — Payroll closed E3 on 2026-05-29; Equb Phase 1 Alpha shipped. This is the most consequential stale claim because README is what a new contributor reads first.
• 25 ADRs (001–025). ADR-015 and ADR-016 are Proposed (no code yet); ADR-018–025 (added 2026-06-18) capture the target-platform decisions; the rest are accepted and code-matched. (This audit was written when only 17 existed.)
• 9 of 11 runbooks are real and useful, contradicting the earlier "9 stubs" guess in docs/audits/CURRENT_STATE_AUDIT.md. That audit needs a one-line correction.

---

2. Phase 1 — Documentation inventory

Legend. K=Keep, M=Merge into another doc, S=Split, A=Archive (move to docs/archive/), D=Delete, R=Rewrite. Sup-by = superseded by.

2.1 Top-level (/)

File	Lines	Purpose	Action	Reason
README.md	272	Project pitch + clone-and-run + status	R	Stale: payroll + equb status. Should be the ONE entry point; today competes with CLAUDE.md / PROJECT_STRUCTURE.md
CLAUDE.md	127	AI-session context	K (trim)	Keep terse (<100 lines); drop everything that duplicates README — keep only non-negotiables + behavioural rules
PROJECT_STRUCTURE.md	202	Intern-friendly layout walk	M → docs/architecture/HANDBOOK.md §1	Pure overlap with README "layout" + HANDBOOK §1. Save the intern-friendly tone, fold into HANDBOOK. Then archive.
SECURITY_CONTROLS.md	663	Partner-questionnaire / control inventory	R	Many "Live" rows are actually Planned. Need an evidence column citing migrations/code. Audience is partners — keep at root for visibility.
INTERN_PROGRAM.md	933	16-week intern curriculum	R	Baseline (§"already in repo") contradicts code — assumes greenfield auth build (svc-identity), but better-auth is Live in apps/api/src/identity/auth/. Re-phase against actual code state.
equb-financial-projection.md	136	Founder pitch / 3-stage revenue model	A (→ docs/business/)	Not engineering doc; doesn't belong at root. Create docs/business/ for material like this.

2.2 docs/ root

File	Lines	Purpose	Action	Reason
docs/README.md	45	Index of docs/	R	Rewrite as the canonical entry index pointing at the new structure
docs/STATUS_LEGEND.md	50	Defines 6 status tags	K	Essential reference; cited by everything
docs/SYSTEM_GAP.md	689	12 gaps in bank-orchestrator transition (all marked [x] FIXED)	A	Snapshot in time. Now historical because gaps are closed. Move to archive with a redirect to current audits.
docs/SYSTEM_GAP_ACTION_PLAN.md	281	Sprint plan for those 12 gaps	A	Same reason — historical. The gaps it sequences are closed.
docs/API_INVENTORY.md	533	HTTP route catalogue (2026-05-29)	A (sup-by docs/audits/API_INVENTORY_FRESH.md)	2 days stale; superseded by the fresh audit. Keep redirect note.

2.3 docs/adr/ (17 files)

File	Status	Action
adr/README.md	Template + governance	K
ADR-001 … ADR-014	Accepted, code-matched	K (all 14)
ADR-015 (adjustment-journal process)	Proposed; blocker for soak gate	K + tag as critical-path in roadmap
ADR-016 (dispute workflow)	Proposed; depends on ADR-015	K + tag as critical-path

All ADRs are accurate. No action needed beyond the two Proposed ones being tracked.

2.4 docs/architecture/ (17 files)

File	Lines	Action	Reason
SYSTEM_OVERVIEW.md	370	K (canonical exec overview)	Newest, evidence-grounded, mermaid diagrams
HANDBOOK.md	496	K (canonical engineer handbook)	Newest; merge in PROJECT_STRUCTURE.md content + system-topology details
restructure-2026-05.md	123	A	Self-marked "complete, historical reference"; belongs in archive
SYSTEM_TOPOLOGY.md	673	M → HANDBOOK.md §8 + new infra docs	Topology / ports / deploy details belong in HANDBOOK or under docs/operations/. Don't keep as standalone
BANK_ORCHESTRATION.md	210	M → ADR-014 supplement / DOMAIN_KNOWLEDGE_BASE	The architectural commitment lives in ADR-014; flow detail belongs in DOMAIN_KB. Cherry-pick what's not redundant, fold in.
MONEY_FLOWS.md	286	M → DOMAIN_KNOWLEDGE_BASE.md	12 canonical money flows — most are duplicated in DOMAIN_KB now. Fold the additional sequence diagrams into DOMAIN_KB.
PAYROLL_ARCHITECTURE.md	303	K	Domain-specific deep dive complementing DOMAIN_KB
ETHIOPIAN_TAX_ENGINE.md	132	K	Compliance + rule-engine reference
RECONCILIATION_ARCHITECTURE.md	252	K	Ops-critical detail not duplicated elsewhere
SLOS_AND_ALERTING.md	172	K	SLO authority
PHASE_C_LOOKUP_ACCOUNT.md	169	A	Phase-specific delivery note; archive once it stops being referenced
DOMAIN_COMPLETENESS_MATRIX.md	224	A (sup-by audits)	Same content covered by docs/audits/CURRENT_STATE_AUDIT.md
REAL_SYSTEM_STATE.md	408	A (sup-by docs/audits/CURRENT_STATE_AUDIT.md)	Self-superseded by the newer audit
SYSTEM_NOT_IMPLEMENTED.md	215	A (sup-by docs/audits/ROADMAP_REALITY_CHECK.md)	Audit covers the same ground with fresher evidence
90_DAY_EXECUTION_PLAN.md	299	K (move to docs/roadmap/)	The one canonical sequenced plan
GO_LIVE_BLOCKERS.md	402	K (move to docs/roadmap/)	Companion to execution plan
PRODUCTION_READINESS.md	291	R + move to docs/operations/	Risk register is stale (Phase C/D closed 4 of 5 risks); re-score

2.5 docs/onboarding/ (12 files)

File	Lines	Action	Reason
README.md	93	R	Rewrite as the index pointing at DEVELOPER_GUIDE + DOMAIN_KB
01-what-is-demozpay.md	272	A (sup-by SYSTEM_OVERVIEW.md + DOMAIN_KB.md)	Has stale "Payroll Planned" claim
02-running-locally.md	321	A (sup-by DEVELOPER_GUIDE.md §2-3)	Stale: Node 20+, port 8000 (real is Node 22.13+, port 3030)
03-the-codebase-tour.md	423	A (sup-by HANDBOOK.md §1)	Stale ledger status ("Compile-only")
04-how-the-backend-works.md	460	A (sup-by HANDBOOK.md + DOMAIN_KB)	Pre-restructure diagrams
05-the-frontend-apps.md	130	K	Accurate; mock-only frontend description still applies
06-status-matrix.md	150	A (sup-by docs/audits/CURRENT_STATE_AUDIT.md)	Stale: payroll marked Planned
07-rules-and-patterns.md	420	K	Seven non-negotiables — current and well-written
08-how-to-add-things.md	414	K	Recipes — current and useful
09-common-mistakes.md	354	K (minor edit re ledger status)	Diagnostics; mostly accurate
DEVELOPER_GUIDE.md	388	K (primary onboarding)	Newest, accurate, hands-on
DOMAIN_KNOWLEDGE_BASE.md	448	K (primary business primer)	Newest, accurate

2.6 docs/runbooks/ (11 files)

File	Status	Action
README.md	Index	K
bank-statement-parse-failed.md	Live	K
cron-migration.md	Stub-template (technical how-to, not a runbook)	R or M into a deployment playbook
drift-detected.md	Live	K
gateway-down.md	Live	K
payroll-ledger-enablement.md	Live	K
payroll-migration-deploy.md	Live	K
permission-matrix.md	Live — canonical RBAC reference	K (move to docs/security/) — it's not really a runbook
sms-smpp-to-http-migration.md	Live	K
transport-swap-pattern.md	Live	K
webhook-failure.md	Live	K

Correction to prior audit: my earlier CURRENT_STATE_AUDIT.md said "9 of 10 runbooks are stub templates." That was wrong — only cron-migration.md is stubby; the rest are real. Will fix.

2.7 docs/security/ (4 files)

All four are coherent, evidence-grounded, no contradictions with code.

File	Action	Note
AUTH_SYSTEM_REVIEW.md	K	Exec summary
AUTH_RISK_MATRIX.md	K	Risk-tracking
AUTH_MIGRATION_STRATEGY.md	K + update	Flag packages/shared/auth/identity as the prerequisite that's now Live (post R1)
LONG_TERM_IAM_ARCHITECTURE.md	K	North-star target

2.8 docs/archive/ (6 files)

File	Action	Note
README.md	K	Guard rail
CORE_BANKING_MICROSERVICES_PLAN.md	K	Has regulatory/FI research value
DEMOZPAY_ARCHITECTURE.md	K	Genesis architecture doc, ADR-referenced
SYSTEM_DOCUMENTATION.md	K	Stale paths, intact domain knowledge
NX_WORKSPACE_EXPLAINED.md	R or D	Replace with a current Nx walkthrough or delete
theme-system-plan.md	D	Fully superseded by packages/shared/ui/README.md

2.9 docs/audits/ (3 new files)

File	Action
API_INVENTORY_FRESH.md	K — supersedes docs/API_INVENTORY.md
CURRENT_STATE_AUDIT.md	K — supersedes REAL_SYSTEM_STATE.md
ROADMAP_REALITY_CHECK.md	K — supersedes SYSTEM_NOT_IMPLEMENTED.md
DOCUMENTATION_AUDIT.md (this file)	K

2.10 Package + service READMEs (27 files)

Every one is hand-authored and substantive. None are Nx scaffolds. All accurate to code. Action: K all 27.

The one nuance: packages/shared/auth/README.md says it's Live; CLAUDE.md tags it Deprecated. After the R1 work, packages/shared/auth is Live as the identity-port boundary — CLAUDE.md is the one that's wrong. Will fix.

2.11 apps/docs-web/ content (21 files)

Cluster	Action
docs/intro.md, docs/architecture/overview.md, docs/api/introduction.md, docs/portals/{admin,business}.md	D — pure boilerplate placeholders
docs/portals/{client,mfi}.md, docs/guides/{contributing,deployment}.md	R — hollow stubs; either fill with real content or delete
docs/tutorial-basics/* (5 files), docs/tutorial-extras/* (2 files)	D — Docusaurus learn-ware, unrelated to DemozPay
blog/2019-05-28-first-blog-post.md, blog/2019-05-29-long-blog-post.md, blog/2021-08-26-welcome/index.md	D — Docusaurus example posts
src/pages/markdown-page.md	D — Docusaurus example
apps/docs-web/README.md	K
sidebars.ts, docusaurus.config.ts	R — when we wire docs-web to surface the real /docs/ content

Decision needed: is docs-web a real public docs site or dead weight? Status today: Stub. Until that decision is made, all the template content is noise.

2.12 dist/ accidentally tracked

11 README.md files under dist/packages/*/ are tracked despite .gitignore:4 ignoring dist/. Action: git rm --cached dist/ in a follow-up commit.

---

3. Phase 2 — Duplication matrix

3.1 The seven major duplication clusters

Cluster A — Stack / repo layout / commands

Document	Section	Overlap
README.md	§"Clone & run" (42-221), §"Repo layout" (155-180)	Authoritative
CLAUDE.md	§"Stack" (24-37), §"Layout" (39-67)	~95% identical to README
PROJECT_STRUCTURE.md	§"Top-level folders" (16-24), §"Generators" (169-179)	~85% identical to README
docs/architecture/HANDBOOK.md	§1 "Monorepo layout"	New; should absorb the intern-friendly tone from PROJECT_STRUCTURE.md
docs/architecture/SYSTEM_TOPOLOGY.md	§"Directory map"	Same content again
docs/onboarding/03-the-codebase-tour.md	Folder-by-folder walk	Same content, plus stale ledger note

Single source of truth: README.md (audience: first-time reader) + docs/architecture/HANDBOOK.md §1 (audience: engineer who already cloned). Delete the duplicates.

Cluster B — System status / what's Live

Document	Coverage	Snapshot date
docs/SYSTEM_GAP.md	12-gap inventory	2026-05-28
docs/SYSTEM_GAP_ACTION_PLAN.md	Sprint plan for those 12 gaps	2026-05-28
docs/architecture/REAL_SYSTEM_STATE.md	Narrative audit	2026-05-29
docs/architecture/DOMAIN_COMPLETENESS_MATRIX.md	23 domains × 15 capabilities	2026-05-29
docs/architecture/SYSTEM_NOT_IMPLEMENTED.md	What's missing, by tier	2026-05-29
docs/architecture/PRODUCTION_READINESS.md	Operational scoring	2026-05-29
docs/onboarding/06-status-matrix.md	Capability matrix	2026-05-31
docs/audits/CURRENT_STATE_AUDIT.md	NEW — Live/Partial/Stub/Dead	2026-05-31

Single source of truth: docs/audits/CURRENT_STATE_AUDIT.md. Archive the four older snapshots; keep docs/onboarding/06-status-matrix.md's table format if a one-page view is wanted (or absorb into CURRENT_STATE_AUDIT).

Cluster C — Roadmap / what to build next

Document	Coverage
docs/SYSTEM_GAP_ACTION_PLAN.md	4-sprint plan for 12 gaps (now closed)
docs/architecture/90_DAY_EXECUTION_PLAN.md	3 × 30-day phases for 22 blockers
docs/architecture/GO_LIVE_BLOCKERS.md	22 blockers with acceptance + effort
docs/architecture/SYSTEM_NOT_IMPLEMENTED.md	Tier 1-4 priority
docs/audits/ROADMAP_REALITY_CHECK.md	NEW — claimed vs. actual, ranked priorities

Single source of truth: keep two docs only — GO_LIVE_BLOCKERS.md (the what — list of blockers) and 90_DAY_EXECUTION_PLAN.md (the when — phased sequence). Archive SYSTEM_GAP_ACTION_PLAN.md (gaps closed) and SYSTEM_NOT_IMPLEMENTED.md (sup-by ROADMAP_REALITY_CHECK). Move both keep-docs into docs/roadmap/.

Cluster D — API surface

Document	Coverage
docs/API_INVENTORY.md	2026-05-29 catalogue
docs/audits/API_INVENTORY_FRESH.md	NEW — 2026-05-31 catalogue with packages/*/backend/presentation/ controllers included

Single source of truth: docs/audits/API_INVENTORY_FRESH.md. Archive the old one with a forward-link.

Cluster E — Architecture / system overview

Document	Audience	Action
docs/architecture/SYSTEM_OVERVIEW.md	Founders, PMs, new devs — NEW	K — canonical exec overview
docs/architecture/HANDBOOK.md	Backend engineers — NEW	K — canonical engineer reference
docs/architecture/SYSTEM_TOPOLOGY.md	Ops + new engineers	M → HANDBOOK §8 (ports, RPCs, deploy)
docs/architecture/BANK_ORCHESTRATION.md	Engineers, architects	M → DOMAIN_KB + ADR-014
docs/architecture/restructure-2026-05.md	Historians	A

Single source of truth: SYSTEM_OVERVIEW.md (exec) and HANDBOOK.md (engineer). Two layers, two audiences.

Cluster F — Onboarding

Document	Action
docs/onboarding/DEVELOPER_GUIDE.md (new)	K — primary entry
docs/onboarding/DOMAIN_KNOWLEDGE_BASE.md (new)	K — primary business primer
docs/onboarding/01-what-is-demozpay.md	A — sup-by SYSTEM_OVERVIEW + DOMAIN_KB
docs/onboarding/02-running-locally.md	A — sup-by DEVELOPER_GUIDE §2-3
docs/onboarding/03-the-codebase-tour.md	A — sup-by HANDBOOK §1
docs/onboarding/04-how-the-backend-works.md	A — sup-by HANDBOOK + DOMAIN_KB
docs/onboarding/06-status-matrix.md	A — sup-by CURRENT_STATE_AUDIT
docs/onboarding/05-the-frontend-apps.md	K
docs/onboarding/07-rules-and-patterns.md	K
docs/onboarding/08-how-to-add-things.md	K
docs/onboarding/09-common-mistakes.md	K

Cluster G — Money flows

Document	Coverage
docs/architecture/MONEY_FLOWS.md	12 canonical flows with status
docs/architecture/BANK_ORCHESTRATION.md	4 architectural flows
docs/onboarding/DOMAIN_KNOWLEDGE_BASE.md	Per-domain money flow
docs/architecture/SYSTEM_OVERVIEW.md §5	3 mermaid sequence diagrams

Single source of truth: DOMAIN_KNOWLEDGE_BASE.md (business view) and SYSTEM_OVERVIEW.md (architectural view). Merge MONEY_FLOWS.md content into the relevant per-domain section of DOMAIN_KB, archive the original.

3.2 The most consequential stale claims (code wins)

Claim	Doc	Reality
"Payroll: Planned"	README.md:14, docs/onboarding/01-what-is-demozpay.md, 06-status-matrix.md	Live (backend) — E3 closed 2026-05-29, 38 use cases, 22+ events, 34 tests, 24 Prisma models. Code: packages/payroll/
"Equb / savings: Planned"	README.md:19	Equb Live Phase 1 Alpha — 8 use cases, 8 events, 6 Prisma models incl. partner-bank escrow. Code: packages/equb/. Savings remains Planned.
"Ledger Go server is Compile-only"	restructure-2026-05.md:86, 03-the-codebase-tour.md	Live — all 8 RPCs implemented; 7 store integration tests pass. Code: services/ledger/internal/server/
"Phone OTP: Partial"	restructure-2026-05.md:89	Live — phoneNumber plugin wired; SMS via pluggable module
"Node 20+ required"	02-running-locally.md:10	Node 22.13+ (pnpm@11 requires it) — apps/api/Dockerfile, observed pnpm failure
"API on port 8000"	02-running-locally.md, 04-how-the-backend-works.md	Port 3030 (offset to coexist with telemedhin). README.md:75, infra/docker-compose.full.yml
"LookupAccount stub / DANGEROUS"	BANK_ORCHESTRATION.md, DOMAIN_COMPLETENESS_MATRIX.md	Live (Phase C closed 2026-05-29) — services/integration-gateway/internal/server/lookup_and_health.go
"EWA/Lending repayment Planned"	DOMAIN_COMPLETENESS_MATRIX.md	Live admin path — RecordEwaRepaymentUseCase, RemitInstallmentToFiUseCase
"svc-identity (new NestJS service) to be built by interns"	INTERN_PROGRAM.md §9	Better-auth is Live in apps/api/src/identity/auth/ — no separate identity service. Intern plan needs re-baselining.
"TLS 1.3 mandatory"	SECURITY_CONTROLS.md §A.1	Planned — no enforcement; HMAC over plain TCP between services. Status tag says Planned but body text says "mandatory"
"9 of 10 runbooks are stubs"	docs/audits/CURRENT_STATE_AUDIT.md (mine)	Only cron-migration.md is template. 9 of 10 are real runbooks. My audit is wrong.
"packages/shared/auth is Deprecated"	CLAUDE.md:36	Live — superseded application (better-auth) but the package is the identity-port boundary, actively imported. Should be tagged Live.

---

4. Phase 3 — New documentation structure

4.1 The target tree

docs/
├── README.md                          # NEW — single entry-point, ~80 lines, links only
│
├── ARCHITECTURE/                      # capital so it's visually distinct from old layout
│   ├── SYSTEM_OVERVIEW.md             # exec-level (✓ already written)
│   ├── HANDBOOK.md                    # engineer-level (✓ already written; absorbs PROJECT_STRUCTURE + SYSTEM_TOPOLOGY)
│   ├── LEDGER.md                      # NEW — extracted from HANDBOOK §5
│   ├── BANK_ORCHESTRATION.md          # (existing; one architectural commitment doc tied to ADR-014)
│   ├── RECONCILIATION.md              # rename of RECONCILIATION_ARCHITECTURE.md
│   └── SLOS_AND_ALERTING.md           # ops contract
│
├── DOMAINS/
│   ├── DOMAIN_KNOWLEDGE_BASE.md       # canonical business + flows (✓ already written)
│   ├── PAYROLL.md                     # rename of PAYROLL_ARCHITECTURE.md
│   ├── ETHIOPIAN_TAX_ENGINE.md        # compliance reference
│   └── (future) BNPL.md, SAVINGS.md   # when those packages land
│
├── API/
│   ├── INVENTORY.md                   # ✓ API_INVENTORY_FRESH.md, renamed
│   └── (future) per-endpoint detail
│
├── SECURITY/
│   ├── README.md                      # NEW — index
│   ├── PERMISSION_MATRIX.md           # moved from runbooks/
│   ├── AUTH_SYSTEM_REVIEW.md
│   ├── AUTH_RISK_MATRIX.md
│   ├── AUTH_MIGRATION_STRATEGY.md
│   └── LONG_TERM_IAM_ARCHITECTURE.md
│
├── OPERATIONS/
│   ├── PRODUCTION_READINESS.md        # rewritten + moved from architecture/
│   ├── SLOS_AND_ALERTING.md           # symlink-of-record from ARCHITECTURE/
│   └── LOCAL_DEVELOPMENT.md           # NEW — extracted from DEVELOPER_GUIDE §2-4
│
├── ROADMAP/
│   ├── README.md                      # NEW — index
│   ├── EXECUTION_PLAN_90_DAY.md       # ✓ 90_DAY_EXECUTION_PLAN.md, renamed
│   ├── GO_LIVE_BLOCKERS.md            # ✓ existing
│   └── PRIORITIES.md                  # derived from ROADMAP_REALITY_CHECK §6
│
├── DECISIONS/                          # rename of adr/
│   ├── README.md
│   ├── ADR-001..ADR-016                # all 17 files
│   └── (template)
│
├── RUNBOOKS/
│   ├── README.md                      # index — 11 real runbooks
│   ├── bank-statement-parse-failed.md
│   ├── drift-detected.md
│   ├── gateway-down.md
│   ├── payroll-ledger-enablement.md
│   ├── payroll-migration-deploy.md
│   ├── sms-smpp-to-http-migration.md
│   ├── transport-swap-pattern.md
│   ├── webhook-failure.md
│   └── deployment-tasks.md            # NEW — absorbs cron-migration.md
│
├── AUDITS/
│   ├── DOCUMENTATION_AUDIT.md         # this file
│   ├── CURRENT_STATE_AUDIT.md         # ✓ existing
│   └── ROADMAP_REALITY_CHECK.md       # ✓ existing
│
├── ONBOARDING/                         # smaller than today
│   ├── README.md                      # NEW — the one-stop index
│   ├── DEVELOPER_GUIDE.md             # ✓ existing
│   ├── RULES_AND_PATTERNS.md          # rename of 07-rules-and-patterns.md
│   ├── HOW_TO_ADD_THINGS.md           # rename of 08-how-to-add-things.md
│   ├── COMMON_MISTAKES.md             # rename of 09-common-mistakes.md
│   ├── FRONTENDS.md                   # rename of 05-the-frontend-apps.md
│   └── DOMAIN_KNOWLEDGE_BASE.md       # symlink-of-record from DOMAINS/
│
├── PRODUCT/                            # NEW — for biz/founder material
│   ├── README.md
│   └── EQUB_FINANCIAL_PROJECTION.md   # moved from repo root
│
├── STATUS_LEGEND.md                   # stays at docs/ root — universal reference
│
└── ARCHIVE/
    ├── README.md                       # guard rail
    ├── (existing 6 files)
    ├── SYSTEM_GAP.md                   # archived (gaps closed)
    ├── SYSTEM_GAP_ACTION_PLAN.md       # archived
    ├── API_INVENTORY.md                # archived (sup-by AUDITS/INVENTORY)
    ├── REAL_SYSTEM_STATE.md            # archived (sup-by AUDITS)
    ├── SYSTEM_NOT_IMPLEMENTED.md       # archived (sup-by AUDITS)
    ├── DOMAIN_COMPLETENESS_MATRIX.md   # archived
    ├── PHASE_C_LOOKUP_ACCOUNT.md       # archived (phase-specific)
    ├── restructure-2026-05.md          # archived (self-marked historical)
    ├── MONEY_FLOWS.md                  # archived (folded into DOMAIN_KB)
    ├── BANK_ORCHESTRATION.md           # archived after merge into ADR-014 + DOMAIN_KB
    ├── SYSTEM_TOPOLOGY.md              # archived after merge into HANDBOOK §8
    ├── 01-what-is-demozpay.md          # archived
    ├── 02-running-locally.md           # archived
    ├── 03-the-codebase-tour.md         # archived
    ├── 04-how-the-backend-works.md     # archived
    └── 06-status-matrix.md             # archived

Top-level (/)

README.md                              # single project intro, ~150 lines, points at docs/
CLAUDE.md                              # ~90 lines: non-negotiables + AI behaviour
PROJECT_STRUCTURE.md                   # DELETE (content folded into HANDBOOK)
SECURITY_CONTROLS.md                   # KEEP for partner visibility; REWRITE with evidence column
INTERN_PROGRAM.md                      # KEEP at root; REWRITE baseline
equb-financial-projection.md           # MOVE to docs/PRODUCT/

apps/docs-web/

Decision: either gut and re-wire, or delete.

• If we wire docs-web up: delete docs/, blog/, src/pages/markdown-page.md from inside docs-web; replace sidebars.ts with a sidebar mirroring the new docs/ tree above; symlink-import the real docs/ content.
• If we don't: leave docs-web in Stub status indefinitely; nothing broken, just visible noise.

Recommendation: wire it (option 1) once the cleanup above lands.

4.2 Why each top-level folder

Folder	Why
ARCHITECTURE/	Patterns + system shape. Engineer reference.
DOMAINS/	Business + domain primer per domain. Per-domain README is inside the package; deep dives live here.
API/	Catalogue of HTTP/gRPC surface. Single inventory file plus future per-endpoint detail.
SECURITY/	Auth model, RBAC, threat model, prior reviews.
OPERATIONS/	Day-2 ops: dev setup, production readiness, SLOs.
ROADMAP/	What we will build next. Two docs only (blockers + plan).
DECISIONS/	The ADRs. The "why" of every rule.
RUNBOOKS/	First-responder playbooks per failure mode.
AUDITS/	Snapshots in time. Living docs are elsewhere.
ONBOARDING/	New-hire path; six docs only.
PRODUCT/	Business material; founder pitch decks etc.
ARCHIVE/	Out-of-date docs preserved for reference.

---

5. Phase 4 — New-developer onboarding review

The thought experiment. A developer joins on a Monday morning. What do they read? What confuses them? What slows them down?

5.1 What they should read first (in the new structure)

When	Doc	Time
Morning 1	README.md (top-level)	5 min
Morning 1	docs/ARCHITECTURE/SYSTEM_OVERVIEW.md	30 min
Morning 1	docs/ONBOARDING/DEVELOPER_GUIDE.md §1-5	45 min
Morning 1	clone + boot stack (DEVELOPER_GUIDE.md §2-3)	60 min
Afternoon 1	docs/DOMAINS/DOMAIN_KNOWLEDGE_BASE.md	60 min
Afternoon 1	docs/DECISIONS/ — all 16 ADRs	90 min
Day 2	docs/ARCHITECTURE/HANDBOOK.md	90 min
Day 2	docs/ONBOARDING/RULES_AND_PATTERNS.md	30 min
Day 3	Pick a domain. Read its package README + docs/DOMAINS/<DOMAIN>.md if it exists. Trace one HTTP request from controller to ledger.	half a day

Total reading time before contributing: ~6 hours, spread across 2 days.

5.2 What is confusing today

1. Three different "where to start" docs at the root: README.md, CLAUDE.md, PROJECT_STRUCTURE.md. A new dev opens all three and notices contradictions (the payroll status mismatch alone is enough to undermine trust).
2. Eight competing status docs. A new dev who wants to know "what's actually built?" finds SYSTEM_GAP.md, REAL_SYSTEM_STATE.md, DOMAIN_COMPLETENESS_MATRIX.md, SYSTEM_NOT_IMPLEMENTED.md, 06-status-matrix.md, CURRENT_STATE_AUDIT.md, API_INVENTORY.md, ROADMAP_REALITY_CHECK.md. They don't know which to trust.
3. Onboarding split between old and new. docs/onboarding/01-09 and DEVELOPER_GUIDE.md say different things about Node version, port, and payroll status.
4. Docs-web is a Docusaurus tutorial template. A new dev who opens it sees "Tutorial Basics: Create a Page" — and thinks the project is unfinished or abandoned.
5. INTERN_PROGRAM.md says interns will "build svc-identity" — but the codebase has better-auth Live in apps/api/src/identity/auth/. The intern plan reads like fiction.
6. SECURITY_CONTROLS.md mixes Live with Planned without clearly partitioning. A partner reading it thinks "TLS 1.3 mandatory" — which is documented as Planned.

5.3 What's missing

• Single project intro for a non-engineer. README.md mixes pitch with clone-and-run; a PM or partner has to skim. A 1-page docs/PRODUCT/INTRODUCTION.md would help.
• First-issue checklist. "Here are 5 issues a new contributor can pick up today" — none of the onboarding docs name concrete starter tasks.
• Glossary. Done in DOMAIN_KB §15; needs to be linked from README.md and DEVELOPER_GUIDE.md.
• Per-domain runbook index. Today there's one runbooks folder for all of ops; map runbooks to domains so a payroll engineer reads only payroll runbooks.
• A real Nx primer for engineers new to monorepos. The existing one in docs/archive/NX_WORKSPACE_EXPLAINED.md is stale.

5.4 What appears too many times

Topic	Where it appears today	Recommended single source
Repo layout	README + CLAUDE + PROJECT_STRUCTURE + HANDBOOK + 03-codebase-tour + SYSTEM_TOPOLOGY (×6)	docs/ARCHITECTURE/HANDBOOK.md §1
Money is santim	README + CLAUDE + every domain README + every ADR + every architecture doc	ADR-005 + one line in HANDBOOK
RLS / tenant isolation	README + CLAUDE + ADR-013 + RLS.md + every domain README + SYSTEM_GAP + restructure	ADR-013 + RLS.md (apps/api/prisma/)
Ledger as truth	README + CLAUDE + ADR-006 + ADR-012 + LEDGER doc + every flow doc	ADR-006 + new LEDGER.md
"What's Live today"	8 docs (see §3.1 cluster B)	docs/AUDITS/CURRENT_STATE_AUDIT.md
"What's next"	5 docs (see §3.1 cluster C)	docs/ROADMAP/ (2 files only)
Money flow walk	MONEY_FLOWS + BANK_ORCHESTRATION + DOMAIN_KB + SYSTEM_OVERVIEW (×4)	docs/DOMAINS/DOMAIN_KNOWLEDGE_BASE.md per-domain section

5.5 Recommended onboarding path (post-cleanup)

Day 1 — orient

• Read: README.md → docs/ARCHITECTURE/SYSTEM_OVERVIEW.md → docs/STATUS_LEGEND.md.
• Run: clone repo, docker compose up, hit every health endpoint, open Prisma Studio.
• Read all 16 ADRs.

Day 2 — internalise the patterns

• Read: docs/ARCHITECTURE/HANDBOOK.md (full).
• Read: docs/ONBOARDING/RULES_AND_PATTERNS.md.
• Read: docs/DOMAINS/DOMAIN_KNOWLEDGE_BASE.md.

Day 3 — see one flow end-to-end

• Pick EWA. Read packages/ewa/README.md, all 4 use cases, the EWA controller in apps/api/src/products/ewa/, the Go ledger handler services/ledger/internal/server/post_transaction.go. Trace a POST /api/ewa/requests/:id/disburse from controller → use case → ledger → integration-gateway → mock bank → webhook → ConfirmSettlement.
• Run the EWA test suite. Modify one assertion. Watch it fail.

Day 4 — touch the schema

• Read docs/STATUS_LEGEND.md again, then docs/AUDITS/CURRENT_STATE_AUDIT.md to find a documented gap.
• Pick a small bug or test gap (e.g. one of the KYC use cases that lacks a spec). Write the spec. Get it green. Open a PR.

Day 5 — write your first real change

• Pick a small feature from docs/ROADMAP/GO_LIVE_BLOCKERS.md that aligns with your domain. Pair with a reviewer. Land a small slice.
• Read docs/ONBOARDING/HOW_TO_ADD_THINGS.md recipe for whatever you're touching.

By end of week 1, a new engineer should:

• Be able to boot the stack from scratch.
• Know which doc to consult for each kind of question.
• Have one merged PR.

---

6. Phase 5 — Document quality scores

Scored 1-10 on four axes. Total /40. Only major docs scored — package READMEs, ADRs, and runbooks are uniformly high (~8-9/10 each) and not scored individually.

6.1 The best documents (keep, model others on these)

Doc	Acc	Comp	Maint	DX	Total	Why it's good
docs/STATUS_LEGEND.md	10	10	10	10	40	Tiny, precise, universally referenced
docs/adr/ADR-013-tenant-isolation.md	10	10	10	9	39	RLS pattern documented end-to-end
docs/adr/ADR-006-ledger-sole-source-of-truth.md	10	10	9	9	38	Foundational, code-matched
services/ledger/README.md	10	9	9	10	38	Self-contained service explanation
packages/shared/money/README.md	10	9	9	10	38	Crystal clear on santim semantics
docs/audits/CURRENT_STATE_AUDIT.md (new)	9	9	8	9	35	Evidence-grounded, file:line cited
docs/onboarding/07-rules-and-patterns.md	10	9	8	8	35	The seven non-negotiables; durable
docs/runbooks/drift-detected.md	10	9	9	8	36	Real runbook with steps + diagnosis
docs/runbooks/webhook-failure.md	10	9	9	8	36	Same shape
docs/runbooks/permission-matrix.md	9	9	8	9	35	Canonical RBAC reference

6.2 The dangerous documents (action required — they actively mislead)

Doc	Acc	Comp	Maint	DX	Total	Specific lies
README.md (top-level)	5	8	6	7	26	Says Payroll + Equb are Planned; both are Live. First doc a new dev reads.
INTERN_PROGRAM.md	4	9	4	6	23	Plan-builds-svc-identity contradicts better-auth being Live in apps/api/src/identity/auth/
SECURITY_CONTROLS.md	5	9	5	5	24	"TLS 1.3 mandatory" + status=Planned — partner-facing doc with contradictory claims
docs/onboarding/02-running-locally.md	4	7	4	5	20	Wrong Node version, wrong port, missing infra/docker-compose.full.yml flow
docs/onboarding/01-what-is-demozpay.md	5	7	5	6	23	"Payroll Planned — no payroll domain package"
docs/onboarding/06-status-matrix.md	5	8	6	7	26	Stale payroll row
docs/architecture/REAL_SYSTEM_STATE.md	6	8	5	7	26	Self-superseded by the new audit
docs/architecture/DOMAIN_COMPLETENESS_MATRIX.md	6	8	4	7	25	EWA/Lending repayment marked Planned; LookupAccount marked DANGEROUS — both Live
docs/architecture/restructure-2026-05.md	7	8	4	8	27	Says ledger Go server is Compile-only; it has 8 RPCs Live
docs/SYSTEM_GAP_ACTION_PLAN.md	6	8	5	6	25	Header says "no commits while standing instruction in force" — gaps are closed, instruction is stale

6.3 The bulk of the mid-tier

All package READMEs, all ADRs (except 015/016 which are Proposed), all 9 real runbooks, my four new audit docs, HANDBOOK.md, SYSTEM_OVERVIEW.md, DOMAIN_KNOWLEDGE_BASE.md, DEVELOPER_GUIDE.md, the security docs — all score 30-36/40. They are the documentation that should remain.

6.4 Score summary

Tier	Count	Action
Excellent (35+)	~30 docs	Keep, treat as templates
Good (28-34)	~30 docs	Keep, occasional edits
Needs rewrite (22-27)	~10 docs	Rewrite or archive
Dangerous (<22)	~3 docs	Rewrite urgently
Boilerplate / template / scaffold	~30 docs (docs-web template + dist + archive)	Delete or wipe

---

7. Phase 6 — Cleanup execution plan

Constraint: every batch is a single PR that runs git mv + edits without touching application code. Reviewable in <30 min.

Week 1 — kill the lies

Day	Work	PR
Mon	Fix README.md payroll + equb status. Add date stamp _Last reviewed: 2026-05-31_. Link to docs/audits/ for ground truth.	#1
Mon	Fix CLAUDE.md payroll line + packages/shared/auth tag (Deprecated → Live).	#1
Tue	Move equb-financial-projection.md → docs/PRODUCT/. Delete apps/docs-web/docs/tutorial-basics/*, tutorial-extras/*, blog/*, src/pages/markdown-page.md. Delete docs/portals/admin.md, business.md.	#2
Tue	git rm --cached dist/ — remove the 11 accidentally-tracked README files.	#3
Wed	Archive cluster B (system status): move SYSTEM_GAP.md, SYSTEM_GAP_ACTION_PLAN.md, REAL_SYSTEM_STATE.md, DOMAIN_COMPLETENESS_MATRIX.md, SYSTEM_NOT_IMPLEMENTED.md → docs/archive/. Add forward-links to docs/audits/CURRENT_STATE_AUDIT.md.	#4
Wed	Archive cluster D: move docs/API_INVENTORY.md → docs/archive/. Rename docs/audits/API_INVENTORY_FRESH.md → docs/API/INVENTORY.md.	#4
Thu	Archive cluster F onboarding: move 01-04, 06 → docs/archive/. Rename 05 → FRONTENDS.md, 07-09 to keyword names. Update docs/onboarding/README.md to be the new index.	#5
Fri	One-line fix in docs/audits/CURRENT_STATE_AUDIT.md about runbooks ("only cron-migration.md is template, not 9 of 10").	#6

Output: 6 PRs. ~30 docs archived. README + CLAUDE.md no longer mislead.

Week 2 — merge the duplicates

Day	Work	PR
Mon	Merge PROJECT_STRUCTURE.md content into HANDBOOK.md §1. Archive PROJECT_STRUCTURE.md.	#7
Mon	Merge SYSTEM_TOPOLOGY.md content into HANDBOOK.md §8. Archive SYSTEM_TOPOLOGY.md.	#7
Tue	Merge MONEY_FLOWS.md into per-domain sections of DOMAIN_KNOWLEDGE_BASE.md. Archive MONEY_FLOWS.md.	#8
Tue	Merge BANK_ORCHESTRATION.md content — keep half in ADR-014 supplement, half in DOMAIN_KB. Archive original.	#8
Wed	Move restructure-2026-05.md → docs/archive/ (self-marked historical).	#9
Wed	Move PHASE_C_LOOKUP_ACCOUNT.md → docs/archive/ (phase-specific delivery note).	#9
Thu	Rename folders: docs/adr/ → docs/DECISIONS/. Update all references.	#10
Thu	Promote runbooks/permission-matrix.md → docs/SECURITY/. Merge cron-migration.md into a new deployment-tasks.md.	#10
Fri	Create docs/ROADMAP/ and move 90_DAY_EXECUTION_PLAN.md + GO_LIVE_BLOCKERS.md there.	#11
Fri	Create docs/OPERATIONS/ and move + rewrite PRODUCTION_READINESS.md.	#11

Output: 5 PRs. Architecture folder shrinks from 17 → 6 files.

Week 3 — rewrite the dangerous

Day	Work	PR
Mon-Tue	Rewrite SECURITY_CONTROLS.md with an evidence column. Each row points to migration/code/test or marks as Planned.	#12
Wed	Rewrite INTERN_PROGRAM.md baseline to match current code state. Re-phase the curriculum so interns build next things, not already done things.	#13
Thu	Write a new top-level README.md that is ~150 lines, points at the new docs/ tree, no duplication.	#14
Thu	Trim CLAUDE.md to <100 lines: just non-negotiables + AI behaviour rules, no duplication.	#14
Fri	Write the new docs/README.md as the canonical index.	#14
Fri	Write docs/ONBOARDING/README.md as the entry point linking DEVELOPER_GUIDE + DOMAIN_KB + RULES + HOW_TO_ADD + COMMON_MISTAKES.	#14

Output: 3 PRs. Three "dangerous" docs fixed. Entry experience clean.

Week 4 — wire docs-web (optional but recommended)

Day	Work
Mon	Decide: wire docs-web or delete. If wire:
Tue	Install @docusaurus/theme-mermaid (the new architecture docs have mermaid diagrams).
Tue-Wed	Replace apps/docs-web/sidebars.ts to mirror the new docs/ tree.
Wed	Symlink-import or git-submodule the real docs/ content into apps/docs-web/docs/.
Thu	Boot, screenshot, send link.
Fri	Document the docs-web wiring in docs/OPERATIONS/.

Output: 1 PR. docs-web Stub → Live.

Cleanup totals

Action	Count
Total markdown files today	143
Keep (after move/rename)	~70
Merge	~10 (content folded elsewhere)
Archive	~25
Delete (boilerplate + dist + obsolete)	~30
Rewrite	~5
Result	~70 active + ~25 archived

---

8. Single source of truth — final assignments

The table every reviewer should consult when asked "where does this belong?":

Topic	The one place
Project pitch + clone-and-run	README.md (top-level)
AI / Claude behaviour rules	CLAUDE.md (top-level, terse)
Repo layout + monorepo structure	docs/ARCHITECTURE/HANDBOOK.md §1
Stack + commands	docs/ARCHITECTURE/HANDBOOK.md + docs/ONBOARDING/DEVELOPER_GUIDE.md
Status tag definitions	docs/STATUS_LEGEND.md
What's actually Live / Partial / Stub today	docs/AUDITS/CURRENT_STATE_AUDIT.md
API endpoints	docs/API/INVENTORY.md
What's next / roadmap	docs/ROADMAP/GO_LIVE_BLOCKERS.md + docs/ROADMAP/EXECUTION_PLAN_90_DAY.md
Architectural decisions ("why")	docs/DECISIONS/ADR-*.md
Money flow per domain	docs/DOMAINS/DOMAIN_KNOWLEDGE_BASE.md
Ledger architecture (deep)	docs/ARCHITECTURE/HANDBOOK.md §5 + services/ledger/README.md
Tax engine (Ethiopia compliance)	docs/DOMAINS/ETHIOPIAN_TAX_ENGINE.md
Payroll deep-dive	docs/DOMAINS/PAYROLL.md
Reconciliation operations	docs/ARCHITECTURE/RECONCILIATION.md
SLOs + alerts	docs/ARCHITECTURE/SLOS_AND_ALERTING.md
Auth + RBAC + permission matrix	docs/SECURITY/PERMISSION_MATRIX.md (+ AUTH_*.md)
Long-term IAM target	docs/SECURITY/LONG_TERM_IAM_ARCHITECTURE.md
Local dev setup	docs/ONBOARDING/DEVELOPER_GUIDE.md §2-3
Production readiness scorecard	docs/OPERATIONS/PRODUCTION_READINESS.md
First-responder playbooks	docs/RUNBOOKS/*.md
Domain business primer	docs/DOMAINS/DOMAIN_KNOWLEDGE_BASE.md
Coding standards + rules	docs/ONBOARDING/RULES_AND_PATTERNS.md
How to add a new endpoint/domain/migration	docs/ONBOARDING/HOW_TO_ADD_THINGS.md
Debugging	docs/ONBOARDING/COMMON_MISTAKES.md
First-week curriculum	docs/ONBOARDING/DEVELOPER_GUIDE.md §9
Intern curriculum	INTERN_PROGRAM.md (top-level)
Partner-facing security stance	SECURITY_CONTROLS.md (top-level)
Founder / business material	docs/PRODUCT/*.md
Historical context	docs/archive/*.md

8.1 The deletion-vs-archive judgement

• Delete = the content is dangerous or pure noise. Docusaurus template, dist accidents, theme-system-plan, the placeholder portals/admin.md etc.
• Archive = the content was once true and may have research/audit value. SYSTEM_GAP (gaps closed but log of how we got here), restructure-2026-05, REAL_SYSTEM_STATE (predecessor of current audit), old onboarding sequence.
• Keep = the content is current and load-bearing today.
• Rewrite = the content is right-shaped but wrong-detailed. README payroll status, SECURITY_CONTROLS evidence column, INTERN_PROGRAM baseline.

8.2 What survives long-term

If we did nothing else, the 20 documents below are enough for a new engineer to understand and work on DemozPay:

1. README.md
2. CLAUDE.md
3. docs/STATUS_LEGEND.md
4. docs/ARCHITECTURE/SYSTEM_OVERVIEW.md
5. docs/ARCHITECTURE/HANDBOOK.md
6. docs/DOMAINS/DOMAIN_KNOWLEDGE_BASE.md
7. docs/ONBOARDING/DEVELOPER_GUIDE.md
8. docs/ONBOARDING/RULES_AND_PATTERNS.md
9. docs/ONBOARDING/HOW_TO_ADD_THINGS.md
10. docs/ONBOARDING/COMMON_MISTAKES.md
11. docs/API/INVENTORY.md
12. docs/AUDITS/CURRENT_STATE_AUDIT.md
13. docs/AUDITS/ROADMAP_REALITY_CHECK.md
14. docs/ROADMAP/GO_LIVE_BLOCKERS.md
15. docs/ROADMAP/EXECUTION_PLAN_90_DAY.md
16. docs/DECISIONS/ADR-001 through ADR-016 (counted as one item)
17. docs/RUNBOOKS/README.md + the 9 live runbooks
18. docs/SECURITY/*.md (4 docs)
19. Every domain package's packages/<x>/README.md
20. Every service's services/<x>/README.md

Everything else is supporting material. Anything beyond this list deserves justification.

---

Closing assertion

DemozPay's documentation is in better shape than it feels, but the volume and contradictions make it feel worse than it is. The cleanup work is mechanical (move, archive, delete) plus three rewrites (README.md, SECURITY_CONTROLS.md, INTERN_PROGRAM.md). After three weeks of effort, the doc tree shrinks from 143 files to ~70 active + ~25 archived, with no information loss — only deduplication, freshness, and clarity gained.

Do this before onboarding the next engineer. The cost of an extra week of doc cleanup is repaid by every future hire reading less and contributing sooner.