Niek Otten
3abf8f7ccf
All checks were successful
## What & why
Finishes **S-12 · Behandel-portal — werkbak + beoordeling**. The backend sub-slices (S-12a/b/c-1/c-2) were merged, but the slice's stated outcome — a behandel *portal* with medewerker login, a werkbak, and decide — had no frontend. This adds it.
- **`libs/auth`**: `MedewerkerAuthService` + `provideMedewerkerAuth` (Keycloak `medewerker` realm), a `roles`/`hasRole` surface on the shared `AuthService`, and a realm-roles protocol mapper so the SPA can read `behandelaar`/`teamlead` from the token. The BFF remains the security boundary (ADR-0013).
- **`apps/behandel`**: a new Nx Angular app mirroring self-service — medewerker OIDC login and a **werkbak** page listing registrations awaiting beoordeling (`GET /behandel/werkbak`) with per-row **Goedkeuren/Afwijzen** actions (`POST /behandel/registrations/{id}/decide`) that refresh the list. NL DS/Utrecht, standalone + signals.
- **e2e**: the walking-skeleton happy path now approves through the real portal (behandelaar logs in, finds the row by reference, clicks Goedkeuren) instead of the temporary admin endpoint.
- **infra/docs**: behandel service in compose (`:8142`, depends on Keycloak); added to the smoke `WAIT_SVCS` + CI log dump; `frontend-decisions.md` and `demo-script.md` updated.
Closes #13
## Definition of Done
- [x] Linked Gitea issue (above).
- [x] Failing test committed before the implementation.
- [x] Implementation makes the test pass; refactor commit if structure improved.
- [x] Conventional Commits referencing the issue (`refs #13`).
- [ ] CI green — all Gitea Actions jobs.
- [x] `docker compose up` from a fresh clone reaches green health checks within 3 minutes. *(behandel image + container verified locally; full stack gated in CI.)*
- [x] Docs updated if behaviour, contracts, or operations changed.
- [x] ADR added — ADR-0013 (merged with the backend sub-slices) already covers the wiring; no new decision here.
- [x] Demo note in `docs/demo-script.md`.
## Notes for reviewers
- Verified locally: auth + behandel + all frontend projects pass lint & unit tests (incl. axe WCAG 2.1 AA); production build green; the behandel Docker image builds and serves with the correct baked `medewerker` config + SPA fallback.
- The full compose-up smoke, e2e, and mutation are CI-gated (known local full-stack verify limits).
- **Follow-ups (not in scope):** the `WerkbakItem` contract has no citizen name (werkbak shows the BSN) — adding one is a BFF+domain contract change; and the domain's temporary admin `approve` endpoint is now unused by the e2e and could be removed.
Reviewed-on: #87
154 lines
11 KiB
Markdown
154 lines
11 KiB
Markdown
# 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 nginx, 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 → nginx forwards to the
|
|
BFF: **no CORS**, and the DigiD token (same-origin) is attached by the interceptor. nginx resolves
|
|
the BFF at request time (a `resolver` + variable `proxy_pass`) so it starts before the BFF is up.
|
|
- **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 nginx, 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 nginx, 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.
|