atomic-design-poc/docs/reference/architecture/0001-bff-lite-decision-dtos.md

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 httpResources (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.

Where the contract lives, after codegen

The paragraph above says "manage it with one source of truth that generates types for both sides". That target state has arrived, so this section states which artifact is now the contract.

The generated client is the wire contract. libs/shared/src/infrastructure/api-client.ts is regenerated from the backend's OpenAPI document by npm run gen:api, and CI fails on drift (the api-client-drift job regenerates it and runs git diff --exit-code). It is the single source of truth for the shape of every endpoint. An adapter consumes its types directly; 19 of the 20 infrastructure adapters do.

A hand-written contracts/*.dto.ts is the exception, for two cases only:

1. Codegen does not reach the endpoint — a hand-rolled fetch/XHR path that the generator never sees.
2. The generator types the shape too loosely — the generated type compiles but is weaker than the wire really is.

In either case the hand-written file must still import nothing. It describes the wire, not the domain.

The parse* trust boundary is unchanged and stays mandatory, whichever way the type arrived. A generated type is a compile-time claim about the wire, not a runtime guarantee: the server can send anything. infrastructure/ validates the untrusted shape and maps it onto the domain, exactly as before.

The four surviving hand-written contracts stay. They are apps/ssp/src/app/registratie/contracts/{brp-address,dashboard-view,duo-diplomas}.dto.ts and libs/beheer/src/contracts/stamdata.dto.ts. All four fall under case 2, and the dashboard view shows why: the generator emits every property as optional, and it flattens a discriminated union into a bag of optional fields.

// generated — every field optional, `tag` a bare string, all variants merged
interface RegistrationStatusDto {
  tag?: string | undefined;
  herregistratieDatum?: string | undefined;
  geschorstTot?: string | undefined;
  reden?: string | undefined;
  doorgehaaldOp?: string | undefined;
}

// hand-written — a real discriminated union, per-variant fields required
type RegistrationStatusDto =
  | { tag: 'Geregistreerd'; herregistratieDatum: string }
  | { tag: 'Geschorst'; geschorstTot: string; reden: string }
  | { tag: 'Doorgehaald'; doorgehaaldOp: string; reden: string };

Adopting the generated shape here would push undefined handling into every consumer and make an illegal state representable, which CLAUDE.md §3 forbids. Retiring these four is therefore not a cleanup to schedule; it becomes correct only if the backend annotates its DTOs so the generator emits required properties and real unions.

Worked example in this POC

Implemented against the real backend, backend/src/BigRegister.Api. Two slices demonstrate both policy shapes.

A. Dashboard profile → one aggregated, decision-enriched call (decision-flag).

• Endpoint: GET /api/v1/dashboard-view (Program.cs), one call replacing three.
• Contract: apps/ssp/src/app/registratie/contracts/dashboard-view.dto.ts (DashboardViewDto = registration + person + decisions).
• Boundary parse: parseDashboardView() in apps/ssp/src/app/registratie/infrastructure/dashboard-view.adapter.ts validates the untrusted shape and maps DTO → domain (hand-written; no schema lib).
• BigProfileStore 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).

B. Intake scholing threshold → config value.

• Endpoint: GET /api/v1/intake/policy (Program.cs), serving IntakePolicy.ScholingThreshold.
• Contract: the generated IntakePolicyDto; the adapter is apps/ssp/src/app/herregistratie/infrastructure/intake-policy.adapter.ts.
• 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)

• Optimistic-update race fix in BigProfileStore (beginHerregistratie/rollbackHerregistratie can leave pending wrong under concurrent submits).
• Multi-tab session sync. The session itself now persists (localStorage, read back through parseStoredPrincipal), but a change in one tab does not reach another — no storage listener exists.

Two bullets were discharged and removed. Runtime DTO validation is no longer "only the dashboard view": 33 parse* boundary functions exist. The OpenAPI codegen toolchain is real: npm run gen:api generates libs/shared/src/infrastructure/api-client.ts and CI drift-checks it.

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.