eho/atomic-design-poc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite the README as the entry point to all documentation

Browse Source 
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>
This commit is contained in:
eho
2026-08-25 14:08:40 +02:00
co-authored by Claude Sonnet 5
parent ae7781efef
commit 0ad02e651a
2 changed files with 150 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+10 -4
View File
@@ -10,9 +10,13 @@ Docs are split by **kind**, and kept out of each other's way:
process-facing material.
Teaching material that is best read **next to the components** lives in Storybook, not
here — see the **Foundations** section (`src/docs/*.mdx`), starting at _Foundations →
Overview_. The `reference/` docs are the long-form source; the Foundations pages are the
condensed, cross-linked curriculum.
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
@@ -24,7 +28,9 @@ condensed, cross-linked curriculum.
| [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. |
@@ -40,7 +46,7 @@ condensed, cross-linked curriculum.
| Doc | What it is |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [backlog/README.md](project/backlog/README.md) | The work-package backlog index (WP-01…WP-48) — the live tracker. |
| [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). |