# 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 (`src/docs/*.mdx`), starting at _Foundations →
Overview_. The `reference/` docs are the long-form source; the Foundations pages are the
condensed, cross-linked curriculum.

## `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).                              |
| [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 (WP-01…WP-28) — the live tracker.               |
| [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.                                |
| [SHOWCASE-ROADMAP.md](project/SHOWCASE-ROADMAP.md)                                               | Superseded roadmap (absorbed into `project/backlog/`) — kept for history.      |