atomic-design-poc/docs

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.