ehoandClaude Opus 5
97d9697a84
Convert the approved readable-codebase plan into the ticket protocol this
repo already uses for long arcs (docs/project/backlog/README.md, 75 work
packages driven to done through it).
Adds docs/project/readable-codebase/ with:
- README.md — the ledger: session protocol, GREEN definition, restart
recovery, the agent loop, and an Order table of 35 tickets with their
dependencies and status.
- PLAN.md — the design record, committed so the repository holds the
complete state. A fresh session needs nothing outside it.
Two properties make the arc restart-safe. Each ticket updates its own
Status line and its README row in the same commit as its code, so the
ledger and git log cannot desync. And the plan lives in the repository,
so recovery is three commands and needs no prior context.
Records one correction found while scaffolding: the 22 abandoned agent
checkouts under .claude/worktrees/ are live registered git worktrees, not
orphaned directories. RD-15 must use `git worktree remove` and verify each
branch tip is an ancestor of main first. Spot-checked four; all are
already merged via 637d500.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Documentation
Docs are split by kind, and kept out of each other's way:
reference/— information. How the system works and why: architecture, decisions (ADRs), the FP/TEA/atomic learning guide, accessibility and UX reference. Stable knowledge, not tied to a sprint.project/— administration. Planning and tracking: the work-package backlog, product requirements (PRDs), and the (superseded) roadmap. This is the moving, process-facing material.
Teaching material that is best read next to the components lives in Storybook, not
here — see the Foundations section (libs/shared/docs/*.mdx, run npm run storybook).
The reference/ docs are the long-form source; the Foundations pages are the condensed,
cross-linked curriculum.
Starting out? Foundations → Learning Path (libs/shared/docs/learning-path.mdx) is a
paced, hands-on three-day route through the codebase; Foundations → Overview
(overview.mdx) is the map of every idea, cross-linked.
reference/ — information
| Doc | What it is |
|---|---|
| architecture/ARCHITECTURE.md | The architecture walkthrough: contexts/layers, state management, parse-don't-validate, the feature recipe, the .NET backend seam. |
| architecture/0001-bff-lite-decision-dtos.md | ADR — BFF-lite endpoints + decision DTOs (backend decides, FE renders). |
| architecture/0002-user-groups-and-bounded-contexts.md | ADR — user groups as actors; identity vs authorization. |
| architecture/0003-cibg-huisstijl.md | ADR — adopt CIBG Huisstijl (vendored Bootstrap 5.2) + the token bridge. |
| architecture/0004-stamdata-as-code.md | ADR — business-tunable reference data as typed, compile-time-validated config (not a production DB). |
| architecture/0005-openzaak-behind-bff.md | ADR — connect to OpenZaak (ZGW APIs) behind the BFF via a config-gated data-source seam; the FE never changes. |
| architecture/0006-test-data-builders.md | ADR — build test data through the production door: type-state builders, reducer replay, and which fixture idiom fits which test. |
| openzaak-integration.md | How the BFF sources cases from OpenZaak (the IZaakSource seam + ZGW client), and how to add the next slice. |
| ../backend/openzaak/README.md | Docker harness for running OpenZaak locally: bring-up, integration test, notifications, teardown. |
| stamdata.md | How stamdata (config-as-code reference data) is laid out, how to add a table with zero UI code, and why coupling stays low. |
| audit-log.md | How the data-minimised authz/PII-reveal audit trail is built, how to audit a new action, and the one-producer-hub coupling. |
| feature-flags.md | How runtime feature flags work (catalog-as-code + runtime state), how to add one, and the hand-wired gating coupling to watch. |
| scaffolding.md | How code generation & scaffolding work: plop generators (gen:value-object/gen:form-machine), the NSwag client (gen:api), showcase snippets, and the skill recipes. |
| roles-and-access.md | The roles/actors + capability model: who can do what, how to switch roles in dev, and what each unlocks. |
| architecture/dependencies.md | Bounded-context + atomic-layer boundaries: the allowed-import rules, how they're enforced (dep:check) and visualized (dep:graph). |
| architecture/dependency-graph.md | Generated mermaid graph of contexts × layers (regenerate with npm run dep:graph). |
| fp-tea-atomic-design.md | Long-form learning guide: FP + The Elm Architecture + atomic design. |
| wcag-checklist.md | Manual WCAG checks automation can't catch (tab order, focus traps, reflow). |
| ui-ux-audit.md | Early UI/UX audit against NL Design System (predates ADR-0003 — read in that light). |
project/ — administration
| Doc | What it is |
|---|---|
| backlog/README.md | The work-package backlog index — the live tracker, with the session protocol. |
| prd/0001-mijn-aanvragen-en-wizardstatus.md | PRD — "Mijn aanvragen": running wizards, application status, document preview. |
| prd/0002-attribute-based-access-control.md | PRD — attribute-based access control in the UI. |
| prd/0003-brief-v2-demo-script.md | Demo script — Brief v2 scenarios mapped to a URL + click path (WP-28). |
| SHOWCASE-ROADMAP.md | Superseded roadmap (absorbed into project/backlog/) — kept for history. |