Edwin van den Houdt
d08f3877f7
Acts on the showcase review. Four workstreams; all tests green (npm run lint, 70 FE tests, ng build, 33 backend tests). Enforcement + CI: - eslint.config.mjs bans `any` and enforces layer/context boundaries (domain ≠ Angular; herregistratie → registratie → shared, auth → shared); `npm run lint` added; ajv 6 scoped to ESLint via nested override. - .github/workflows/ci.yml: FE lint+check:tokens+test+build, backend dotnet test, and an API-client drift check. One form idiom (the headline finding): - change-request-form converged onto the wizard pattern — change-request.machine.ts (Model/Msg/reduce + value objects) + submit-change-request.ts (Result) + a real POST /api/v1/change-requests (server re-validates). Spec + story added; the detail page no longer holds an ad-hoc success signal. Resilience/observability seam: - api-client.provider.ts: request timeout, X-Correlation-Id, Idempotency-Key for writes; comments naming the retry/auth seams. - Backend logs correlation id + a no-PII submit-audit line; /api/v1 prefix + backward-compat note; client regenerated. Quick wins: - Dev tooling excluded from prod: scenario.interceptor wired only under isDevMode() (?scenario= inert in prod); debug panel @if(isDev) (tree-shaken out). - src/environments + apiBaseUrl into provideApiClient (angular.json fileReplacements). - Backend /health + /health/ready. - Debug view PII-minimised (redactProfile: name/address/DOB redacted, BIG masked). - IntakePolicyAdapter (removes inline resource in the intake wizard). - README de-staled; CLAUDE.md gains EN/NL + forms-one-idiom + lint/CI notes. - Stories: text-input, link, data-row, site-header, site-footer, change-request-form. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
153 lines
8.8 KiB
Markdown
153 lines
8.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
Agent guide for this repo. The _why_ lives in `docs/ARCHITECTURE.md`,
|
|
`docs/architecture/0001-bff-lite-decision-dtos.md`, and the learning guide
|
|
`docs/fp-tea-atomic-design.md` (FP + The Elm Architecture + atomic design); this
|
|
file is the _rules_. When a decision below and those docs disagree, the docs win —
|
|
update this file.
|
|
|
|
POC of a Dutch BIG-register self-service portal (healthcare professionals log in,
|
|
view their registration, apply for re-registration). Angular 22, standalone,
|
|
signals. Auth is faked; **data and business rules are served by a minimal ASP.NET
|
|
Core backend** (`backend/`, see its README — in-memory seeded, no DB) and consumed
|
|
through an NSwag-generated typed client. The FE renders the backend's decisions.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm start # ng serve (proxies /api → backend) → http://localhost:4200
|
|
npm test # vitest
|
|
npm run lint # eslint — enforces `any`-free code + import/layer boundaries
|
|
npm run build # ng build (must stay green)
|
|
npm run storybook # component library by atomic layer
|
|
npm run gen:api # regenerate the typed client from the backend OpenAPI doc
|
|
docker compose up # run FE + backend together (Swagger at :5000/swagger)
|
|
cd backend && dotnet test # backend rule + endpoint tests
|
|
```
|
|
|
|
`.npmrc` sets `legacy-peer-deps=true` (Storybook's peer range lags Angular 22).
|
|
Do not run `npm audit fix --force` — it downgrades Angular 22→21. Dev-only
|
|
advisories are pinned via `package.json` `overrides`; the shipped bundle audits clean.
|
|
|
|
## The decisions (non-negotiable working agreements)
|
|
|
|
### 1. DDD: contexts then layers, dependencies point inward
|
|
|
|
`src/app/<context>/<layer>/`. Contexts: `shared`, `auth`, `registratie`,
|
|
`herregistratie`, `showcase` (teaching page, not a feature).
|
|
|
|
| Layer | Job | Angular allowed? |
|
|
| ----------------- | ----------------------------------------- | -------------------------------- |
|
|
| `domain/` | business rules + data types | **No — pure TS.** Has `.spec.ts` |
|
|
| `application/` | coordinate state/tasks (stores, commands) | yes (signals) |
|
|
| `infrastructure/` | where data comes from (HTTP adapters) | yes (HTTP) |
|
|
| `contracts/` | wire DTOs (the FE⇄BE seam) | no |
|
|
| `ui/` | how it looks (components, pages) | yes |
|
|
|
|
**Dependencies only point inward**: `ui → application → domain`; everyone may use
|
|
`shared`; never the reverse. Cross-context only `herregistratie → registratie → shared`,
|
|
`auth → shared`. Imports use aliases as direction statements: `@shared/* @auth/*
|
|
@registratie/* @herregistratie/*`. `domain/` imports nothing from Angular.
|
|
|
|
### 2. Atomic design: folder = layer
|
|
|
|
`shared/ui` atoms → molecules → organisms; `shared/layout` templates (`shell`,
|
|
`page-shell`); context `ui/` pages. Each level only uses levels below. A new page
|
|
should be **composition of existing blocks** — adding building blocks is the
|
|
exception, not the default. Atoms are thin wrappers over Utrecht/RHC CSS classes;
|
|
we own only a small typed `input()` API, the design system does the visuals.
|
|
|
|
### 3. State: make illegal states unrepresentable
|
|
|
|
Default reflex — **if you're about to add a second/third boolean to track state,
|
|
model a discriminated union instead.** Three tools, all in `shared/application`:
|
|
|
|
- **`RemoteData<E,T>`** (`remote-data.ts`) — `Loading | Empty | Failure{error} | Success{value}`.
|
|
Combine sources with `map`/`map2`/`map3`/`andThen` (Failure > Loading > Success).
|
|
Render it via the `<app-async>` molecule (`shared/ui/async`) — one of four
|
|
templates, mutually exclusive by construction. Default loading spinner/skeleton
|
|
is delay-gated (~250ms) so fast connections don't flash.
|
|
- **Elm-style store** (`store.ts` → `createStore(initial, reduce)`) — all state in
|
|
one Model; change only by `dispatch(msg)` → **pure** `reduce(model, msg)`. Models
|
|
are tagged unions (see `herregistratie.machine.ts`, `intake.machine.ts`). Templates
|
|
send messages, never mutate.
|
|
- **`Result<E,T>` + value objects** ("parse, don't validate") — raw input becomes a
|
|
branded type only via a parser returning `Result` (`registratie/domain/value-objects/`:
|
|
`Postcode`, `Uren`, `BigNummer`). Once you hold the type, never re-check it.
|
|
|
|
**Derive, don't store** what you can compute — e.g. the wizard's visible steps are
|
|
`visibleSteps(answers)`, not a stored field (`intake.machine.ts`).
|
|
|
|
**Side effects stay out of the reducer.** A _command_ (`application/submit-*.ts`)
|
|
does the HTTP, then dispatches a message describing the outcome. Reducer = "what the
|
|
new state is"; command = "go do it, then say what happened."
|
|
|
|
**Shared cross-page state = one root singleton.** Stores are `providedIn: 'root'`
|
|
(`BigProfileStore`, `SessionStore`). That single instance is the shared state — no
|
|
NgRx, no extra lib. Optimistic update pattern: `begin*` (flip pending) →
|
|
`confirm*` (clear + `resource.reload()`) / `rollback*` (undo).
|
|
|
|
### 4. BFF-lite + decision DTOs (ADR-0001)
|
|
|
|
`infrastructure/` is the **only** layer that touches the network — the
|
|
anti-corruption boundary. Each screen gets one screen-shaped endpoint returning a
|
|
decision-enriched DTO; **the FE renders decisions, it does not recompute business
|
|
rules.** Per rule, pick: _decision flag_ (server computes the boolean — e.g.
|
|
herregistratie eligibility) or _config value_ (server sends threshold, FE applies
|
|
for instant feedback, server re-validates as authority — e.g. scholing threshold).
|
|
FE keeps only **format** validation, never as authority.
|
|
|
|
DTO lives in `contracts/`; a hand-written `parse*`/`toDomain` in `infrastructure/`
|
|
validates the untrusted shape and maps DTO → domain. Wiring a real .NET backend
|
|
touches only `infrastructure/` + `contracts/` (see ARCHITECTURE §6). Server-owned
|
|
rules stay in `domain/*.policy.ts` as reference impl + unit test, marked server-owned,
|
|
but the FE doesn't call them.
|
|
|
|
### 5. Testing
|
|
|
|
Vitest. Co-locate `*.spec.ts` next to the unit. **Domain and pure logic must have a
|
|
spec** (reducers, combinators, `visibleSteps`, parsers, boundary `parse*` adapters).
|
|
Test the pure function directly — no Angular TestBed for domain. UI is exercised via
|
|
Storybook stories (`*.stories.ts` co-located, titled `Layer/Name`, a11y addon on),
|
|
not heavy component tests.
|
|
|
|
## Conventions
|
|
|
|
- Standalone components only; no NgModules. Signal inputs (`input()`), `inject()` over
|
|
constructor DI (constructor only for `effect()`/template-ref injection).
|
|
- Angular-native control flow `@if/@for`; fetch via `resource({ loader })` over the
|
|
generated `ApiClient` inside an `infrastructure/*.adapter.ts` (one place HTTP lives),
|
|
with a `parse*` boundary; `withViewTransitions()` for page transitions (header/footer
|
|
have stable `view-transition-name`, excluded from the fade).
|
|
- **Naming:** shared/reusable UI is **English** (language-agnostic: `button`,
|
|
`wizard-shell`); domain contexts are **Dutch** (`registratie`, `herregistratie`,
|
|
`*.machine.ts`). Pick the language by which side of the seam the code is on.
|
|
- **Forms = one idiom.** Any form with validation or submission uses a `*.machine.ts`
|
|
(Model/Msg/reduce) + value objects + a `submit-*` command returning `Result` — the
|
|
same shape as the wizards, whether it's one step or many. Don't hand-roll mutable
|
|
fields + ad-hoc error signals.
|
|
- Routes: lazy `loadComponent`, persistent `ShellComponent` parent, `canActivate:
|
|
[authGuard]` on protected routes (`app.routes.ts`).
|
|
- Theming is one import — `src/styles.scss` pulls the RHC palette; no hand-written theme.
|
|
- Scenario toggle (**dev-only**, not wired in prod builds): `?scenario=slow|loading|empty|error`
|
|
on data pages (`scenario.interceptor.ts`) to see every async state.
|
|
- Prettier; `.editorconfig`. tsconfig: `noImplicitReturns`,
|
|
`noPropertyAccessFromIndexSignature`, `noFallthroughCasesInSwitch`, `isolatedModules`.
|
|
- **Enforced, not just hoped-for:** `npm run lint` (`eslint.config.mjs`) fails the build
|
|
on `any` and on illegal imports — `domain/` importing Angular, or a context importing
|
|
"upward" (the `herregistratie → registratie → shared`, `auth → shared` direction).
|
|
CI (`.github/workflows/ci.yml`) runs lint + `check:tokens` + test + build, backend
|
|
`dotnet test`, and an API-client drift check.
|
|
|
|
## Adding a feature (recipe)
|
|
|
|
Domain first (types + pure rules + spec, no Angular) → infrastructure (adapter:
|
|
`httpResource` or command returning `Result`) → application (store if shared state;
|
|
union + pure reduce) → UI last (compose `shared/ui` atoms, wrap async in `<app-async>`,
|
|
dispatch messages). Worked example: the intake wizard (`herregistratie/`).
|
|
|
|
## Out of scope (POC, don't build unprompted)
|
|
|
|
Real auth/DigiD, real backend, i18n, NgRx, licensed Rijkshuisstijl font/logo,
|
|
runtime DTO validation on every endpoint, multi-tab session sync, OpenAPI codegen.
|