ehoandClaude Sonnet 5
6fa27d1c53
Three seams WP-71 documented but left unguarded.
Deletes the FE's isHerregistratieEligible and isStatusConsistent — both
uncalled, the first dead by its own doc-comment. Their tests used fixtures
completely disjoint from the backend's (the backend even had an exact-window
boundary case the FE lacked), so the two sides could diverge indefinitely
without failing anything. CLAUDE.md's policy of keeping server-owned rules
as FE "reference impls" is what kept them alive, so it is amended: the FE may
mirror a server-supplied value for instant feedback, never reimplement the
algorithm. registration.policy.ts keeps its three live exports.
check-seam.sh now also guards the Besluit tag list — the C# enum and the TS
BESLUIT_TAGS array are identical ordered name lists with nothing linking
them, and Enum.TryParse fails at request time rather than build time. Anchored
on the full declaration so it avoids the "greps all matches" trap WP-69 hit.
The phone-format divergence turned out to be real, not latent as recorded:
the backend returned 422 for +31612345678 and (06) 12345678, both of which
the FE's own parseTelefoonnummer accepts. A grep check would have compared
the shared ^0\d{9}$ regex and reported all clear — the difference was in
stripping. RejectPhoneChange now strips what the FE strips, pinned by a
contract test.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
131 lines
7.4 KiB
Markdown
131 lines
7.4 KiB
Markdown
# ADR 0001 — Frontend⇄backend: BFF-lite endpoints + decision DTOs
|
||
|
||
Status: Accepted · Date: 2026-06-26
|
||
|
||
## Problem
|
||
|
||
The frontend makes many separate calls and aggregates them itself, and business
|
||
rules are hardwired in the client. Two concrete symptoms:
|
||
|
||
- The dashboard stitched **three** independent `httpResource`s (BIG-register
|
||
registration, BRP person, notes) together client-side. Each could be
|
||
loading/erroring independently → inconsistent snapshots ("state out of sync").
|
||
- Policy was duplicated on the client: the scholing threshold (`1000`) and the
|
||
herregistratie eligibility window (`12` months) lived in frontend code. If the
|
||
backend changes a rule, the UI silently diverges — bad for governance.
|
||
|
||
Goal: **unify FE/BE policy, cut the number of calls, and make the rules
|
||
transparent/auditable — without coupling the two sides too tightly.** We own the
|
||
backend team.
|
||
|
||
## Options considered
|
||
|
||
| Option | Fewer calls? | Unifies policy? | Cost |
|
||
| -------------------------------------------------------------- | ------------------------- | --------------------------------------------------------- | --------------------------- |
|
||
| 1. Status quo (client calls upstreams, aggregates, owns rules) | No | No | — |
|
||
| 2. Unified client API layer (one facade in the FE) | No — still N round-trips | No — rules still on client | Low, but misses the goal |
|
||
| **3. Screen-shaped endpoints on our own backend ("BFF-lite")** | **Yes** — 1 call/screen | **Yes** — server computes decisions | Low–medium |
|
||
| 4. Separately-deployed BFF service | Yes | Yes | Medium — another deployable |
|
||
| 5. GraphQL gateway | Yes (client picks fields) | **No, not by itself** — still need resolvers to own rules | Medium–high; new infra |
|
||
|
||
GraphQL solves over/under-fetching but does not, on its own, move rules
|
||
server-side — and our problem is policy unification + drift, not field-selection
|
||
flexibility. Option 4 is option 3 with a deployment boundary added.
|
||
|
||
## Decision
|
||
|
||
**Screen-shaped ("BFF-lite") endpoints that return decision-enriched DTOs, defined
|
||
by a single shared contract. The frontend renders decisions; it does not recompute
|
||
them.** Keep it minimal: implement BFF-shaped endpoints on the backend we already
|
||
own. Promote to a separately-deployed BFF service only when a second consumer
|
||
(mobile/partner) or a team boundary demands it — not before.
|
||
|
||
### Why DTOs _decouple_ rather than couple
|
||
|
||
The coupling people fear comes from **not** having DTOs — i.e. serializing internal
|
||
DB/domain entities straight onto the wire, so every schema change ripples to the
|
||
client. A DTO is the decoupling seam:
|
||
|
||
```
|
||
DB entity / domain model → DTO (the wire contract) → FE view model
|
||
(backend's own) (the agreed contract) (frontend's own)
|
||
```
|
||
|
||
Each side keeps its own internal model and refactors freely; only the DTO is a
|
||
deliberate, versioned change. The one coupling that remains — both sides agreeing
|
||
on the contract — is the _wanted_, reviewable seam. Manage it with **one source of
|
||
truth** (OpenAPI or TypeSpec) that **generates types for both sides**. That spec is
|
||
the governance/transparency artifact.
|
||
|
||
### Two shapes of "policy over the wire" — pick per rule
|
||
|
||
- **Config value** — for simple thresholds. Server sends the value; the FE applies
|
||
it for instant feedback; **the backend re-validates on submit as the authority.**
|
||
Example here: the scholing threshold.
|
||
- **Decision flag** — for anything non-trivial/sensitive. Server computes the
|
||
boolean (optionally with a `reason`); the FE just renders it. Example here:
|
||
herregistratie eligibility.
|
||
|
||
The frontend keeps only **format** validation (postcode shape, integer parsing) for
|
||
instant feedback — never as the authority.
|
||
|
||
## Worked example in this POC
|
||
|
||
This POC has no real backend (static mock JSON + fake submit timers), so the
|
||
"BFF output" is a static file; the `decisions` block stands in for what the backend
|
||
would compute. Two slices were implemented to demonstrate **both** policy shapes:
|
||
|
||
**A. Dashboard profile → one aggregated, decision-enriched call (decision-flag).**
|
||
|
||
- Contract: `src/app/registratie/contracts/dashboard-view.dto.ts`
|
||
(`DashboardViewDto` = registration + person + `decisions`).
|
||
- Endpoint: `public/mock/dashboard-view.json` (one call replaces three).
|
||
- Boundary parse: `parseDashboardView()` in
|
||
`src/app/registratie/infrastructure/dashboard-view.adapter.ts` validates the
|
||
untrusted shape and maps DTO → domain (hand-written; no schema lib for one
|
||
contract).
|
||
- `BigProfileStore` now derives `profile` and `decisions` from the single
|
||
validated view (was a 3-resource `map2`). One request → one consistent snapshot.
|
||
- `herregistratie.page.ts` reads `decisions.eligibleForHerregistratie` instead of
|
||
computing it client-side. That rule is server-owned: it lives only in
|
||
`HerregistratieRule.cs`, with no FE mirror to drift from it (WP-75).
|
||
- The unused upstream adapters/mocks (`brp.adapter.ts`, `registration.json`,
|
||
`brp.json`) were deleted — those calls live behind the BFF now.
|
||
|
||
**B. Intake scholing threshold → config value.**
|
||
|
||
- Contract: `src/app/herregistratie/contracts/intake-policy.dto.ts`.
|
||
- Endpoint: `public/mock/intake-policy.json` (`{ "scholingThreshold": 1000 }`).
|
||
- `intake.machine.ts`: the hardcoded `LAGE_UREN_DREMPEL` constant is gone;
|
||
`lageUren(a, scholingThreshold)` and validation take the value, which lives in
|
||
machine state and is set via a `SetPolicy` message. A `SCHOLING_THRESHOLD_DEFAULT`
|
||
remains only as the offline fallback.
|
||
- `intake-wizard.component.ts` fetches the policy and dispatches `SetPolicy`.
|
||
- WP-69: the backend re-validates the threshold as the authority on submit —
|
||
`IntakePolicy.RejectIncompleteScholing` runs before `POST /applications/{id}/submit`
|
||
(intake-typed) writes anything, 400ing an incomplete scholing answer instead of
|
||
silently accepting a crafted POST that skips it. (WP-72 deleted the legacy
|
||
`POST /intakes` endpoint this once also covered — deleting the surface is a stronger
|
||
fix than 400ing on it.)
|
||
|
||
## Migration sequence (for the real app)
|
||
|
||
1. Define the contract in OpenAPI/TypeSpec; generate types for FE and BE.
|
||
2. Stand up screen-shaped endpoints on the existing backend that aggregate the
|
||
upstreams and compute `decisions`.
|
||
3. Point each screen at its single endpoint; delete client-side aggregation.
|
||
4. Move each hardwired rule server-side; expose as decision flag or config value.
|
||
5. Reduce the FE to format-validation + rendering.
|
||
|
||
## Out of scope here (next steps, not built in the worked example)
|
||
|
||
- Runtime DTO validation on **every** endpoint (only the dashboard view has it).
|
||
- Optimistic-update race fix in `BigProfileStore`
|
||
(`beginHerregistratie`/`rollbackHerregistratie` can leave `pending` wrong under
|
||
concurrent submits).
|
||
- Session persistence / multi-tab sync (`SessionStore` is in-memory).
|
||
- Real OpenAPI/TypeSpec codegen toolchain.
|
||
|
||
ponytail: build the pattern once on one slice; copy it across screens when the real
|
||
backend lands, rather than scaffolding all of it up front.
|