register-referentie/docs/frontend-decisions.md

# Frontend decisions

A running log of frontend tooling and component decisions (CLAUDE.md §10). One entry per
decision; record *why*, and note any deviation from NL Design System.

---

## Workspace & tooling (S-08a, #65)

The portals live in an **Nx monorepo at the repository root**, alongside the .NET `services/`.

- **Package manager: pnpm.** Native build scripts are approved explicitly in `pnpm-workspace.yaml`
  under `allowBuilds` (pnpm 11 fails the install otherwise). Node 24, pnpm 11.
- **Angular, standalone components + signals, no NgModules** (§10). Apps are generated with
  `@nx/angular:application`.
- **Unit tests: Vitest** via Angular's built-in `@angular/build:unit-test` (the `vitest-angular`
  runner). **Angular Testing Library** is added for component tests when the first real components
  land (S-08c); the S-08a placeholder uses a plain `TestBed` render assertion.
- **Lint: ESLint** (flat config, `@nx/eslint`).
- **Nx is scoped to `apps/` + `libs/` only.** The `@nx/docker` and `@nx/dotnet` plugins are **not**
  installed — the .NET services are built by `dotnet`/the Makefile, and `@nx/docker` would otherwise
  infer every `services/*/Dockerfile` as an unnamed Nx project and break the project graph.
- **No Nx Cloud.** `nxCloudId` is stripped from `nx.json`; remote caching would depend on an
  external service, and the repo is Gitea-only (§8.7). Nx's "configure-ai-agents" additions
  (`.claude/settings.json`, a CLAUDE.md section referencing a GitHub marketplace) are **not**
  committed for the same reason.
- **CI:** a `frontend` job (`make frontend` → `pnpm install --frozen-lockfile` + `nx run-many -t
  lint test build`) runs on pnpm + Node, with pinned action URLs (§15).

**NL Design System:** not yet introduced — the S-08a app is a placeholder. NL DS components arrive
with the submit form (S-08c, #67); any deviation from NL DS will be recorded here.

---

## API client generator (S-08b, #66)

`libs/api-client` is **generated from `services/bff/openapi.json`** — never hand-written (§10).

- **Generator: orval** (`client: 'angular'`), a **node-based** generator (no Java, unlike
  `openapi-generator`), so it runs in the pnpm/Node CI lane. It emits an injectable
  `BffApiV1Service` using Angular's `HttpClient` — which means the DigiD bearer token can be attached
  by an **`HttpInterceptor`** (S-08c), the idiomatic Angular approach; a fetch-based SDK would bypass
  the interceptor pipeline.
- **Config:** `libs/api-client/orval.config.ts` (single-file output into `src/lib/generated/`,
  `clean: true`, prettier). **Regenerate with `nx run api-client:generate`** after the BFF spec
  changes; the output is deterministic (idempotent), and `src/lib/generated/` is never hand-edited.
- **Tested** against a mocked BFF via `HttpClientTesting` (`libs/api-client/src/lib/bff-api.spec.ts`).
- The BFF endpoints carry no `operationId`, so orval synthesises method names
  (`postSelfServiceRegistrations`, `getOpenbaarRegister`); adding explicit operation ids to the BFF
  is a possible later polish.

---

## Self-service form: NL DS, DigiD auth, testing (S-08c, #67)

- **NL Design System via `@utrecht/component-library-angular`** (`libs/ui`) + `@utrecht/design-tokens`
  (imported once in `apps/self-service/src/styles.css`). Utrecht is NL DS's reference Angular
  implementation. Its v3 components are **NgModule-based, not standalone**, so `libs/ui` re-exports
  `UtrechtComponentsModule` (and the component classes, so the AOT compiler resolves the template
  directives through the barrel); standalone components consume it via `imports: [UtrechtComponentsModule]`.
  §10's "no NgModules in new code" governs *our* code — consuming a third-party module is fine.
- **DigiD login via `angular-auth-oidc-client`** (`libs/auth`): auth-code + PKCE against the Keycloak
  `digid` realm (public client `big-portal`). A small **`AuthService` abstraction** (bsn /
  isAuthenticated / login) wraps the library so components and the `authenticatedGuard` depend on a
  mockable surface; a **token `HttpInterceptor`** attaches the bearer to BFF calls (secure route).
  The OIDC `authority`/`secureApiOrigin` are dev defaults in `app.config.ts`; the compose-served app
  overrides them (S-08d), and the browser-vs-container issuer alignment is handled there (ADR-0010).
- **Testing:** component tests use **`@testing-library/angular`** (§10) with `AuthService` and the
  api-client mocked; the **axe** (`vitest-axe`) check runs scoped to WCAG 2.1 AA tags
  (`wcag2a/2aa/21a/21aa`) with the document `lang` set, asserting zero violations on the submit page.
  The real DigiD browser round-trip is exercised in S-08d (Playwright).
- **Module boundaries:** replaced the demo eslint `depConstraints` (`scope:shop`/`scope:shared`, left
  over from the Nx angular template) with a permissive `*` default; scope/type tags can be
  introduced when the portal set grows.

---

## Serving + e2e (S-08d, #68)

- **Served by Caddy, same-origin as the BFF.** The compose `self-service` image serves the built app
  and **reverse-proxies** `/self-service/*` + `/openbaar/*` to the `bff` service. Because the
  api-client uses **relative URLs**, the browser calls the app's own origin → Caddy forwards to the
  BFF: **no CORS**, and the DigiD token (same-origin) is attached by the interceptor. Caddy dials
  the BFF per request through the system resolver, so it starts before the BFF is up, picks up its
  restarts, and resolves the bare `bff` name on every engine — compose, podman and Kubernetes
  (ADR-0034; the `Caddyfile` sits next to each app's `Dockerfile`).
- **Runtime config.** The app fetches `/config.json` before bootstrap (`main.ts`); `appConfig` is a
  factory. The dev default (`public/config.json`) points at `localhost:8180`; the Docker image bakes
  the compose value (`keycloak:8080`). One build, per-environment OIDC authority.
- **e2e runs inside the compose network.** `infra/run-e2e-check.sh` runs Playwright in a container on
  `cg`, so the browser reaches Keycloak as `keycloak:8080` — the **same issuer** the BFF validates
  against (resolves the browser-vs-container mismatch, ADR-0010). It uses the official
  `mcr.microsoft.com/playwright:<version>` image with browsers pre-baked, rather than downloading
  ~150 MB of Chromium on every run (issue #73) — the image tag is kept in lockstep with
  `tests/e2e/package.json`'s `@playwright/test` version. The spec is copied in (`docker cp`), not
  mounted, so it leaves nothing root-owned on the host. Wired as `verify-e2e` in the `verify-stack`
  CI job.
- **e2e treats the portal origin as secure.** In-network the portal is served over plain HTTP on a
  non-localhost origin (`http://self-service`), which is **not a secure context**, so Web Crypto
  (`crypto.subtle`) is unavailable. angular-auth-oidc-client needs it for the PKCE code challenge, so
  `authorize()` throws and the login redirect never fires. Production runs behind HTTPS where this is
  a non-issue; rather than terminate TLS in the throwaway stack, the Playwright config passes
  `--unsafely-treat-insecure-origin-as-secure` (honoured only by the full `channel: 'chromium'`
  build, not the default headless-shell). This emulates the production HTTPS secure context without
  touching the app or its production config.
- `tests/e2e` is a standalone Playwright project (its own `package.json`), not an Nx project — it's a
  live-stack check like the other `verify-*` runners, not part of the `frontend` unit lane.

## Openbaar Register portal (S-09, #10)

- **Anonymous, no auth.** The openbaar register is a public read, so `apps/openbaar` has no
  `angular-auth-oidc-client`, no interceptor, and no `config.json` — `main.ts` bootstraps `appConfig`
  directly with just `provideHttpClient` + `provideRouter`. This is the deliberate contrast to
  self-service and keeps the app trivially cacheable/CDN-able.
- **Same-origin via Caddy, like self-service.** The compose `openbaar` image serves the built app and
  reverse-proxies `/openbaar` to the BFF; the api-client's relative calls stay same-origin (no CORS).
  Served on `:8141`, health-checked over IPv4 (`127.0.0.1`), no Keycloak dependency.
- **Public-safe by construction.** The portal only ever sees the BFF's `OpenbaarProjection.PublicView`
  (id + status); `bsn`/`naam` never leave the BFF. The e2e asserts the bsn never renders.
- **Loads on open, filters on search.** `RegisterPage` fetches the full register on construction and
  re-queries `/openbaar/register?q=` on search — no client-side filtering, the BFF owns the query.

## Behandel portal (S-12, #13)

The staff portal where a behandelaar works the **werkbak** (registrations awaiting beoordeling) and
decides each — goedkeuren or afwijzen. `apps/behandel` mirrors `apps/self-service`; the net-new
frontend work is the medewerker realm auth and the werkbak/decide page. Wiring rationale is in
**ADR-0013**; this entry records the frontend-specific choices.

- **Medewerker realm auth, reusing `libs/auth`.** Staff authenticate against the Keycloak
  `medewerker` realm (public client `big-portal`), not `digid`. Rather than fork the auth lib, the
  abstract `AuthService` grew a **`roles`/`hasRole` surface** (empty for realms without roles, e.g.
  `digid`), and a parallel **`MedewerkerAuthService` + `provideMedewerkerAuth`** were added — same
  auth-code + PKCE config, bound to the medewerker realm, reading the nested `realm_access.roles`
  claim. The library's own `authInterceptor` attaches the token to the relative `/behandel/` calls
  (secure route), exactly as self-service does for `/self-service/`.
- **Roles reach the frontend via a realm mapper.** Keycloak emits realm roles in the access token by
  default but not the ID token/userinfo the SPA reads, so the medewerker `big-portal` client gets a
  **realm-roles protocol mapper** (`realm_access.roles`, added to id + userinfo tokens). The
  **BFF remains the security boundary** (`behandelaar` policy, 401/403 on `/behandel/*`, ADR-0013);
  the frontend role signal is for display/UX, and the werkbak page surfaces a load failure (e.g. a
  403 for a non-behandelaar) rather than swallowing it.
- **Same-origin via Caddy, like the other portals.** The compose `behandel` image serves the built
  app and reverse-proxies `/behandel` to the BFF (relative calls, no CORS). Served on `:8142`,
  health-checked over IPv4 (`127.0.0.1`), depends on Keycloak for the medewerker realm.
- **Werkbak = decide-and-refresh.** `WerkbakPage` loads `GET /behandel/werkbak` on open and renders a
  row per registration (referentie/bsn/status). Goedkeuren/afwijzen `POST /behandel/registrations/
  {id}/decide` and then reload the werkbak, so the handled item drops off (its Flowable `Beoordelen`
  task is completed). Per-row decide buttons carry an `aria-label` including the reference, so the
  e2e (and screen readers) can target a specific registration in a shared werkbak.
- **Testing.** Component tests use `@testing-library/angular` with `BffApiV1Service`/`AuthService`
  mocked and the axe WCAG 2.1 AA check; an `app.config.spec` drives the real interceptor + api-client
  to assert the medewerker token attaches to `/behandel/*` (and not to the anonymous openbaar call).
  The full DigiD-submit → behandel-decide → public INGESCHREVEN round-trip is the Playwright happy
  path.

## Self-service withdrawal: "trek aanvraag in" (S-11c, #12)

The submit confirmation grows a **"Trek aanvraag in"** action so a zorgprofessional can withdraw the
registration they just submitted (`apps/self-service`, on the existing `RegistrationPage`).

- **Keyed by the reference, owner-scoped at the BFF.** The button calls the generated
  `postSelfServiceRegistrationsIdWithdraw(reference)` with the reference the submit returned. The
  DigiD token (attached by the interceptor) carries the bsn the BFF forwards; the domain only lets
  the owner withdraw (a mismatch is 404). No extra identity is entered in the UI.
- **Same confirm-and-surface pattern as submit.** A secondary-action button; on success the page
  switches to an ingetrokken confirmation; a failure is surfaced (`role="alert"`) and the action
  stays available to retry — mirroring how submit handles its failure rather than swallowing it.
- **Testing.** Component tests (`@testing-library/angular`, mocked BFF) cover the button appearing
  after submit, the reference being passed, the ingetrokken confirmation, and the failure path; the
  browser round-trip is `tests/e2e/withdrawal.spec.ts`.