ehoandClaude Sonnet 5
0ad02e651a
The repo had good docs that nobody could find. The root README linked to exactly two documents, while learning-path.mdx — a 375-line paced three-day onboarding curriculum — had zero inbound links and was reachable only by running Storybook and spotting it in the sidebar. docs/README.md indexes ~20 documents and nothing at the root pointed at it either. The README was also describing the pre-monorepo repo. Its centrepiece atomic-design table was fictional: it claimed the folder structure IS the hierarchy, with atoms/molecules/organisms/templates/pages directories that exist nowhere. The truth is a better story and now replaces it — two orthogonal axes, DDD on disk (context, then layer) and the atomic ladder in the Storybook sidebar, which comes from story titles. Every other path was stale too (src/app/, src/styles.scss, src/locale/, proxy.conf.json), the second app was entirely absent, and 6 of 36 npm scripts were documented, omitting `npm run ci` — the pre-push gate. Adds a signpost table organised by what you are trying to do, a repo map, the commands that matter, and keeps one corrected showcase section so the repo still makes its case. Also fixes the index it now points at: docs/README.md cited Foundations pages at src/docs/*.mdx, claimed the backlog ran to WP-48 (it is at 75 — the range is dropped so it cannot go stale again), and was missing ADR-0006 and the OpenZaak harness. Verified rather than assumed: all 12 README links and every docs/README.md link resolve, every named npm script exists, no stale path survives, and the quick start was executed — backend serves swagger and the API on :5000, behandelportal serves on :4201. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
54 lines
8.4 KiB
Markdown
54 lines
8.4 KiB
Markdown
# 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](reference/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](reference/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](reference/architecture/0002-user-groups-and-bounded-contexts.md) | ADR — user groups as actors; identity vs authorization. |
|
||
| [architecture/0003-cibg-huisstijl.md](reference/architecture/0003-cibg-huisstijl.md) | ADR — adopt CIBG Huisstijl (vendored Bootstrap 5.2) + the token bridge. |
|
||
| [architecture/0004-stamdata-as-code.md](reference/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](reference/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](reference/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](reference/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](../backend/openzaak/README.md) | Docker harness for running OpenZaak locally: bring-up, integration test, notifications, teardown. |
|
||
| [stamdata.md](reference/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](reference/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](reference/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](reference/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](reference/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](reference/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](reference/architecture/dependency-graph.md) | Generated mermaid graph of contexts × layers (regenerate with `npm run dep:graph`). |
|
||
| [fp-tea-atomic-design.md](reference/fp-tea-atomic-design.md) | Long-form learning guide: FP + The Elm Architecture + atomic design. |
|
||
| [wcag-checklist.md](reference/wcag-checklist.md) | Manual WCAG checks automation can't catch (tab order, focus traps, reflow). |
|
||
| [ui-ux-audit.md](reference/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](project/backlog/README.md) | The work-package backlog index — the live tracker, with the session protocol. |
|
||
| [prd/0001-mijn-aanvragen-en-wizardstatus.md](project/prd/0001-mijn-aanvragen-en-wizardstatus.md) | PRD — "Mijn aanvragen": running wizards, application status, document preview. |
|
||
| [prd/0002-attribute-based-access-control.md](project/prd/0002-attribute-based-access-control.md) | PRD — attribute-based access control in the UI. |
|
||
| [prd/0003-brief-v2-demo-script.md](project/prd/0003-brief-v2-demo-script.md) | Demo script — Brief v2 scenarios mapped to a URL + click path (WP-28). |
|
||
| [SHOWCASE-ROADMAP.md](project/SHOWCASE-ROADMAP.md) | Superseded roadmap (absorbed into `project/backlog/`) — kept for history. |
|