ehoandClaude Opus 5
f19185ed81
ADR-0002 SS3 models Zorgverlener/Medewerker as different Principal variants with different login flows. Actor #2 (apps/behandelportal) landed in WP-61/67 and the union never followed: grep -rn "Principal" returned one hit, a comment. Both apps' auth/domain/session.ts stayed byte-identical (`{ bsn, naam }`), so the backoffice's Behandelaar carried a BSN and logged into the backoffice as a citizen, by DigiD, under a fabricated citizen's name (login.page.ts). The divergence ADR-0002 predicted took an orthogonal side door instead (medewerker.interceptor.ts's X-Medewerker/X-Rollen stamp, which never touches SessionStore) -- which is why ssp/auth and bhp/auth still measured as 100%/84% duplicated after ADR-C-006 shared the route guards. RB-09 (landed the day before) made the backend's IIdentityProvider able to say "no identity" and fail closed; this ticket is its named FE half. Each app's auth/domain/session.ts becomes principal.ts, holding the one Principal variant that app actually has an actor for: ssp keeps `{ kind: 'zorgverlener', bsn, naam }` (G1 still strips the BSN before persisting); behandelportal gets `{ kind: 'medewerker', medewerkerId, naam, rollen }` (no BSN to strip -- G2 shape validation only). A new MedewerkerAdapter replaces DigidAdapter in behandelportal, resolving the existing MEDEWERKER_ID/currentRollen() dev stand-in into a Principal; because there is no credential to check, it returns Principal directly rather than a Result whose error variant could never occur. login.page.ts stops being a BSN/wachtwoord form -- one explainer line and an "Inloggen met SSO" button -- and its dead error-handling branch goes with the Result wrapper that justified it. Measured with tools/baseline-scan.mjs --dup: auth duplication drops from 168/168 (ssp) and 168/200 (bhp) to 32/179 and 32/259 -- under the backlog's <40 target. What remains is the ADR-C-006 route-guard re-export (deliberately identical), generic test/story-file boilerplate, and one shared fragment of the root-singleton-store idiom -- not re-converged identity or login-flow logic. SS3's prediction that the two actors would authenticate differently enough to justify not sharing auth has now actually been tested, not just asserted, and held. Also: renamed Session.bsn to Principal.bsn in two doc comments (libs/shared/src/infrastructure/subject.ts, subject.interceptor.ts) that cited the old type name; regenerated libs/shared/docs/behaviour-spec.mdx (generated file, per its own banner); recorded the resolution in ADR-0002 as a new amendment, replacing its "Known debt" section. 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. |