fix(test): match the catalogus zaaktype cell exactly, not case-insensitively (refs #130)

## What & why

S-16c, the last of the S-16 (#17) split, on top of the backplane (#122) and distributed tracing (#123). The five .NET services now expose OpenTelemetry **metrics** in Prometheus format at `/metrics`; Prometheus scrapes each (one job per service); and Grafana ships a pre-built **Request path — golden signals** dashboard (traffic / errors / latency / saturation), split by service.

Closes #124

### How

- Each service adds `.WithMetrics(AddAspNetCoreInstrumentation + AddHttpClientInstrumentation + AddMeter("System.Runtime") + AddPrometheusExporter)` and maps `/metrics`. Same shape as the S-16b tracing wiring already in these `Program.cs` files.
- `infra/observability/prometheus/prometheus.yml`: one scrape job per service (`acl`, `domain`, `bff`, `event-subscriber`, `projection-api`), reached by compose service name.
- `infra/observability/grafana/provisioning/dashboards/`: dashboard provider + `golden-signals.json` (baked into the Grafana image by the existing `COPY provisioning/`).
- `verify-metrics` (new CI verify-stack step + Makefile target): generates BFF traffic and asserts Prometheus scraped the golden-signal metric from every service. Mirrors `verify-tracing`.

### Dependency (CLAUDE.md §13/§14)

Adds `OpenTelemetry.Exporter.Prometheus.AspNetCore` `1.17.0-beta.1` (matched to the `1.17.0` core already in use). It gives the OTel-native `/metrics` pull endpoint; replacing it would mean hand-rolling Prometheus exposition over a `MeterListener`; the risk is that it is a **prerelease** package (the whole OTel .NET Prometheus line is `-beta`) — pinned, wired only in `Program.cs`, and gated by `verify-metrics`. Recorded in **ADR-0024**.

## Definition of Done

- [x] Linked Gitea issue (#124).
- [x] Failing test committed before the implementation (`test(bff): /metrics exposes http-server request duration`).
- [x] Implementation makes the test pass.
- [ ] CI green — pending Gitea Actions run.
- [x] `docker compose up` reaches green health within 3 min (backplane images unchanged in shape; not on the health gate, ADR-0023).
- [x] Docs updated — demo-script S-16c entry.
- [x] ADR added — ADR-0024.
- [x] Demo note in `docs/demo-script.md`.

## Notes for reviewers

- `/health` polls are counted as traffic (metrics aren't path-filtered, unlike traces). Fine for a demo dashboard and honest — real load stacks on top.
- `projection-api` has no Stryker config (unchanged); the four mutated services carry the metrics wiring in `Program.cs`, same as the merged S-16b tracing code.
- Metric names verified against a live service: `http_server_request_duration_seconds{,_bucket,_count}`, label `http_response_status_code`, `dotnet_process_cpu_time_seconds_total`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: #129

.gitea/workflows/ci.yaml

@@ -9,6 +9,12 @@ on:
 permissions:
   contents: read
 
+# Supersede stale runs: a new push to the same branch/PR cancels the previous run, so the runner's
+# concurrency slots aren't spent on commits nobody is waiting for (refs #127).
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 # Self-hosted runner — see docs/runbooks/ci.md for the runner setup.
 # `uses:` are absolute, tag-pinned URLs (CLAUDE.md §8.7 / §15).
 
@@ -23,6 +29,16 @@ jobs:
       - uses: https://github.com/actions/setup-dotnet@v4
         with:
           dotnet-version: '10.0.x'
+      # Cache the NuGet package store so each .NET job restores from disk, not the network. There are
+      # no lock files (so setup-dotnet's built-in cache doesn't apply); key on the project files. @v3
+      # avoids the GHES guard that breaks @v4 on Gitea (gitea-actions-gotchas.md); cache is best-effort
+      # — a miss just restores from the network. See issue #73.
+      - uses: https://github.com/actions/cache@v3
+        with:
+          path: ~/.nuget/packages
+          key: nuget-${{ runner.os }}-${{ hashFiles('**/*.csproj') }}
+          restore-keys: |
+            nuget-${{ runner.os }}-
       - run: make lint
 
   build:
@@ -32,6 +48,12 @@ jobs:
       - uses: https://github.com/actions/setup-dotnet@v4
         with:
           dotnet-version: '10.0.x'
+      - uses: https://github.com/actions/cache@v3
+        with:
+          path: ~/.nuget/packages
+          key: nuget-${{ runner.os }}-${{ hashFiles('**/*.csproj') }}
+          restore-keys: |
+            nuget-${{ runner.os }}-
       - run: make build
 
   unit:
@@ -41,6 +63,12 @@ jobs:
       - uses: https://github.com/actions/setup-dotnet@v4
         with:
           dotnet-version: '10.0.x'
+      - uses: https://github.com/actions/cache@v3
+        with:
+          path: ~/.nuget/packages
+          key: nuget-${{ runner.os }}-${{ hashFiles('**/*.csproj') }}
+          restore-keys: |
+            nuget-${{ runner.os }}-
       - run: make unit
 
   # Frontend (Nx/Angular) lane: install with pnpm, then Nx lint + test + build.
@@ -64,6 +92,12 @@ jobs:
       - uses: https://github.com/actions/setup-dotnet@v4
         with:
           dotnet-version: '10.0.x'
+      - uses: https://github.com/actions/cache@v3
+        with:
+          path: ~/.nuget/packages
+          key: nuget-${{ runner.os }}-${{ hashFiles('**/*.csproj') }}
+          restore-keys: |
+            nuget-${{ runner.os }}-
       - run: make mutation
       # Publish the Stryker HTML reports. `if: always()` uploads them even when the
       # ratchet fails — that is exactly when you want to inspect the survivors.
@@ -101,12 +135,20 @@ jobs:
           path: services/bff/StrykerOutput/**/reports/mutation-report.html
           if-no-files-found: warn
 
-  # One stage for every check that needs the live stack. On the single self-hosted
-  # runner jobs run sequentially, so booting OpenZaak once (instead of once per job)
-  # is the cheapest layout (issue #58). No setup-dotnet: the ACL test runs in a built
-  # image and everything reaches services by container IP. Needs Docker + egress
+  # One stage for every check that needs the live stack. Booting OpenZaak once (instead
+  # of once per job) is the cheapest layout (issue #58). No setup-dotnet: the ACL test runs
+  # in a built image and everything reaches services by container IP. Needs Docker + egress
   # (base images, nuget, selectielijst.openzaak.nl).
+  #
+  # `needs: [mutation]` is NOT a data dependency — it serialises the two memory-heavy jobs so
+  # they never co-schedule now the runner has capacity >1. A concurrent Stryker run + full-stack
+  # bring-up + Playwright browser on one host is what OOMs the e2e (commit d5e5fa2, #126). The
+  # light .NET/frontend jobs have no `needs`, so they still parallelise up to runner capacity.
+  # `if: !cancelled()` keeps verify-stack running even when the mutation ratchet fails (so we don't
+  # lose its signal) while still honouring run cancellation from the concurrency group above.
   verify-stack:
+    needs: [mutation]
+    if: ${{ !cancelled() }}
     runs-on: ubuntu-latest
     steps:
       - uses: https://github.com/actions/checkout@v4
@@ -114,6 +156,8 @@ jobs:
       # reaches green health" smoke (it replaces the old compose-smoke job).
       - name: Bring up the full stack & wait for health
         run: make verify-up
+      - name: Observability backplane (Grafana + Tempo + Prometheus datasources)
+        run: OBS_TIMEOUT=180 make verify-observability
       - name: ACL ↔ OpenZaak integration tests
         run: make verify-acl
       - name: OpenZaak → NRC notification delivery
@@ -124,10 +168,16 @@ jobs:
         run: make verify-domain
       - name: BFF → Keycloak + domain + projection
         run: make verify-bff
+      - name: Distributed traces reach Tempo (one connected trace across services)
+        run: TRACING_TIMEOUT=120 make verify-tracing
+      - name: Golden-signal metrics scraped by Prometheus (/metrics on every service)
+        run: METRICS_TIMEOUT=120 make verify-metrics
+      - name: Self-service e2e (Playwright, login → submit → success)
+        run: make verify-e2e
       # Log dump must precede teardown (which removes the containers).
       - name: Dump container logs on failure
         if: failure()
-        run: docker compose -f infra/docker-compose.yml logs --no-color --tail=100 oz-init openzaak nrc-init nrc-web nrc-celery nrc-beat flowable-db flowable-rest flowable-init keycloak acl bff domain projection-db event-subscriber projection-api 2>&1 || true
+        run: docker compose -f infra/docker-compose.yml logs --no-color --tail=100 oz-init openzaak nrc-init nrc-web nrc-celery nrc-beat flowable-db flowable-rest flowable-init keycloak acl bff domain projection-db event-subscriber projection-api self-service openbaar behandel beheer tempo prometheus grafana 2>&1 || true
       - name: Tear down
         if: always()
         run: make down

.gitignore

@@ -52,3 +52,9 @@ vite.config.*.timestamp*
 vitest.config.*.timestamp*
 
 .angular
+
+# Playwright e2e (installed/generated in-container or on local runs)
+tests/e2e/node_modules/
+tests/e2e/test-results/
+tests/e2e/playwright-report/
+__pycache__/

BACKLOG.md

@@ -162,20 +162,36 @@ The skeleton proves the spine end-to-end: a registration, a workflow, a zaak in
 
 **Out of scope (whole of S-08):** document upload, status tracking page.
 
-### S-09 · Openbaar Register portal — public lookup
+### S-09 · Openbaar Register portal — public lookup *(#10)*
 
-**Outcome:** The openbaar Angular app shows a search box. Anonymous. Queries the BFF's `/openbaar/register` which reads only the projection's **public-safe** fields. Confirms the walking skeleton end-to-end.
+**Outcome:** The openbaar Angular app shows a search box. Anonymous. Queries the BFF's `/openbaar/register` which reads only the projection's **public-safe** fields. Shows the public-visibility half of the walking skeleton.
+
+_Split from the original S-09 — scoped to the portal only; the approval flow is **S-09b (#75)**._
 
 **Acceptance:**
 
-- E2E test: zorgprofessional registers via self-service (S-08), behandelaar approves via a temporary admin endpoint (no behandel-portal yet), openbaar register shows the entry.
-- Public-safe field whitelist enforced and tested.
+- E2E test: after a zorgprofessional registers via self-service (S-08), the openbaar register shows the entry (as `INGEDIEND`).
+- Public-safe field whitelist enforced and tested (already in the BFF; add a portal component test + a11y check).
 
-**Touches:** `apps/openbaar/`, projection-api hardening, tests.
+**Touches:** `apps/openbaar/`, compose serving, e2e, docs.
 
-**Out of scope:** advanced search filters, sorting.
+**Out of scope:** approval/status transition (S-09b), advanced search filters, sorting.
 
-**End of walking skeleton.** Demo: submit → process → projection → public visibility. All CI gates green on Gitea Actions. Cut release `vYYYY.MM.0` and publish via Gitea Releases.
+### S-09b · Approval flow — temp admin endpoint + status transition to projection *(#75)*
+
+**Outcome:** A behandelaar approves a submitted registration via a temporary admin endpoint (no behandel-portal yet — S-12). The approval transitions the zaak status through the ACL → NRC → event-subscriber → projection, and the openbaar register then shows the entry as approved.
+
+**Acceptance:**
+
+- A new terminal/approved status (e.g. `INGESCHREVEN`) exists and is projected.
+- Temporary admin approve endpoint transitions a registration via a real ZGW status set (behind the ACL, §8).
+- E2E: register (S-08) → approve → openbaar shows the entry as approved.
+
+**Touches:** `services/domain`, `services/acl`, `services/event-subscriber`, `services/projection-api`, e2e.
+
+**Out of scope:** behandel-portal UI (S-12), assessment logic (S-13), escalation (S-15).
+
+**End of walking skeleton** (S-09 + S-09b). Demo: submit → process → projection → public visibility. All CI gates green on Gitea Actions. Cut release `vYYYY.MM.0` and publish via Gitea Releases.
 
 ---
 
@@ -183,9 +199,25 @@ The skeleton proves the spine end-to-end: a registration, a workflow, a zaak in
 
 ### S-10 · Document upload + boundary timer for document timeout (Flow 2)
 
-**Outcome:** BPMN extended with a "wacht op documenten" user task with a 30-day boundary timer. Self-service portal supports diploma upload. On timeout the case is cancelled.
+Split (issue #11 closed) into two independently-demoable slices per §13 — the original spanned six net-new surfaces including a new ZGW boundary:
 
-**Acceptance:** BDD scenarios for both branches; integration tests for the timer firing.
+#### S-10a · Document-wait task + 30-day timeout cancellation + provision trigger — #102
+
+**Outcome:** BPMN gains a `WachtOpDocumenten` user task with a 30-day (P30D) interrupting boundary timer. On timeout the case is cancelled — the timer runs to a dedicated cancel end-event and the domain aggregate moves to a new terminal status `Verlopen` via an external-worker (mirrors S-14 escalation / S-11 withdrawal). "Documents received" is wired end-to-end (domain endpoint + BFF + a "Documenten aanleveren" button on the self-service page) so the walking-skeleton e2e stays green — but the document is **not yet stored** in ZGW; that is S-10b.
+
+**Acceptance:** BDD both branches (documents-in-time vs timeout-cancel); live timer-fire via the management-API "move" idiom; the registration e2e provides documents before the behandelaar step.
+
+#### S-10b · Real diploma upload stored via the ACL Documenten API — #103
+
+**Outcome:** the self-service "Documenten aanleveren" action becomes a real file upload; the file (base64-encoded end-to-end) is stored in the ZGW Documenten (DRC) API as an `enkelvoudiginformatieobject` and related to the zaak, with all document calls routed through the ACL (§8.1, ADR-0018). Builds on the S-10a trigger/wait. Depends on #102.
+
+**Acceptance:** ACL Documenten gateway integration test (real OpenZaak); Playwright e2e uploads a real PDF.
+
+#### S-10c · Close the ZGW zaak on document-timeout expiry — #106
+
+**Outcome:** when the 30-day term lapses (S-10a `RegistratieVerlopen`), the ZGW zaak is set to a distinct non-terminal `Geannuleerd` status + `Vervallen` resultaat (not just the domain aggregate → `Verlopen`), resolved by name in the ACL. Adds the cancellation statustype/resultaattype to the seed + an ACL `CancelZaakAsync`/`POST /annuleringen` + expiry-worker wiring. Carved from S-10b (ADR-0017/0018/0019). Depends on #103.
+
+**Acceptance:** ACL↔OpenZaak integration test (cancellation records `Geannuleerd` + a resultaat, live); the domain verify script fires the P30D timer and asserts the zaak reaches `Geannuleerd` end-to-end; BDD asserts the zaak is cancelled on timeout but untouched when documents arrive in time.
 
 ### S-11 · Withdrawal (Flow 3)
 
@@ -207,21 +239,39 @@ The skeleton proves the spine end-to-end: a registration, a workflow, a zaak in
 
 **Outcome:** Boundary timer on beoordeling user task — 14 days. On timeout, reassigns to a teamlead role.
 
+### S-26 · Self-service — resume an existing registration after refresh — #111
+
+**Outcome:** a signed-in zorgprofessional who reloads the self-service portal (or returns later) gets back to their in-flight registration and its actions (Documenten aanleveren, Trek aanvraag in), instead of a blank submit form with the reference lost. Today all post-submit state lives in in-memory signals, the reference is not in the URL, and there is no self-service read endpoint — so a reload strands the registration. Adds an owner-scoped (DigiD bsn) `GET /self-service/registrations` on the BFF/domain and a load-on-init/route restore in the portal.
+
+**Acceptance:** BDD — resume after refresh shows the existing registration; lookup is owner-scoped (never another citizen's); a user with no in-flight registration still sees the submit form. Playwright e2e reloads mid-flow and asserts the actions remain reachable.
+
 ---
 
 ## Iteration 3 — Maintenance portal and observability *(milestone: `Iteration 3 — Beheer & Observability`)*
 
-### S-15 · Beheer-portal — catalogus & default-fill rules
+### S-15 · Beheer-portal — catalogus & default-fill rules *(split — #16 closed)*
 
 **Outcome:** Beheer portal lets an admin view ZTC catalogi (read-only first), and manage the ACL's default-fill configuration via a CRUD UI. MFA on the medewerker realm enforced.
 
-### S-16 · OpenTelemetry traces + Grafana dashboard
+Split into independently deployable sub-slices (CLAUDE.md §13):
+
+- **S-15a** (#130) · Beheer portal skeleton + read-only catalogi viewer — new beheer Angular app (medewerker-realm login) showing ZTC catalogi/zaaktypen read-only, via a BFF `/beheer/*` read endpoint proxying a read-only ACL Catalogi endpoint (§8.1, reuses the ADR-0021 Catalogi client).
+- **S-15b** (#131) · ACL default-fill configuration CRUD — the `Acl__Defaults__*` config (ADR-0003) becomes a managed store with CRUD via the BFF + a portal UI. Depends on S-15a.
+- **S-15c** (#132) · Enforce MFA (OTP) on the Keycloak medewerker realm.
+
+### S-16 · OpenTelemetry traces + Grafana dashboard *(split — #17 closed)*
 
 **Outcome:** Traces span portal → BFF → Domain → ACL → OpenZaak and portal → BFF → Domain → Flowable. Grafana dashboards pre-built for golden signals.
 
-### S-17 · Quartz.NET scheduler — herregistratie reminder sweep
+Split into independently deployable sub-slices (CLAUDE.md §13):
 
-**Outcome:** Nightly job that finds entries within 90 days of expiry and emits a domain event. (No outbound notification in v1 — logged.)
+- **S-16a** (#122) · Observability backplane — Grafana Tempo + Prometheus + Grafana in compose, datasources auto-provisioned (ADR-0023). No collector; config baked into built images.
+- **S-16b** (#123) · Distributed traces across the five .NET services (OTLP → Tempo; traceparent propagates via the typed HttpClients). Depends on S-16a. ✅
+- **S-16c** (#124) · Prometheus metrics + golden-signal Grafana dashboards. Depends on S-16a. ✅
+
+### S-17 · Quartz.NET scheduler — herregistratie reminder sweep ✅
+
+**Outcome:** Daily Quartz.NET cron job finds inscriptions within 90 days of their herregistratie deadline and reminds each (flag on the aggregate + log). No outbound notification and no domain event in v1 — the reminder is the persisted flag, surfaced on the read model (ADR-0022, #120). Quartz fires time-triggered sweeps; the existing pumps stay as queue-drainers.
 
 ---
 

CHANGELOG.md

@@ -2,19 +2,130 @@
 
 All notable changes to this project. Generated from Conventional Commits by git-cliff.
 
-## Unreleased
+## v2026.07.0 — 2026-07-14
+
+### Architecture
+- ADR-0005 adopt Stryker.NET for mutation testing (refs #47)
+- ADR-0006 — provision the ACL integration test against the compose stack (refs #46)
+- ADR-0007 + runbooks for the OZ→NRC notification wiring (refs #56)
+- ADR-0009 external-task job-worker pattern (refs #6, #60)
+- ADR-0010 BFF OIDC validation + downstream boundaries (refs #8, #63)
+
+### Bug Fixes
+- Pin OpenZaak/NRC image tags; add smoke log capture on failure (refs #30)
+- Harden oz-db healthcheck and raise compose-up timeout (refs #30)
+- Bake config into images so compose-smoke passes on CI (refs #30)
+- Nrc-init runs migrations only, not setup_configuration (refs #30)
+- Smoke waits on durable services, not the whole project (refs #30)
+- Portable health poll instead of compose --wait (refs #30)
+- Pin upload-artifact to @v3 — @v4 refuses to run on Gitea (refs #47)
+- Buffer the zaak POST body so OpenZaak accepts it (refs #46)
+- Keep dotnet format green under the shared .editorconfig (refs #65)
+- Re-export the full Utrecht package from libs/ui (refs #67)
+- Run checkAuth() at startup to end the login redirect loop (refs #67)
+- Health-check nginx over IPv4 (127.0.0.1) (refs #68)
+- Treat the http portal origin as secure so DigiD PKCE login works (refs #68)
+- Attach the DigiD token to relative BFF calls (refs #68)
+
+### Build
+- Pin Stryker.NET as a local dotnet tool (refs #47)
 
 ### CI
 - Gitea Actions pipeline + runner runbook (refs #30) (#37)
+- ACL Dockerfile + full compose stack for smoke test (refs #30)
+- Switch runner label to ubuntu-latest (refs #30)
+- Run the mutation ratchet as a parallel CI job (refs #47)
+- Publish the Stryker HTML report as a CI artifact (refs #47)
+- Run the ACL integration test as a Gitea Actions job (refs #46)
+- Keep the integration lane local-only; document the runner gap (refs #46)
+- Run the ACL integration test in CI inside the compose network (closes #55) (refs #46)
+- Run the Event Subscriber + projection-api in compose and verify end-to-end (refs #7)
+- Containerize, wire into compose, and verify end-to-end (refs #6)
+- Make Stryker report upload best-effort (refs #62)
+- Retrigger after runner cleanup (refs #6)
+- Retrigger CI (refs #6)
+- Retrigger CI after gitea restart (refs #6)
+- Compose wiring, verify-bff live check, mutation baseline (refs #8)
+- Nx frontend lane (lint/test/build) (refs #65)
+- Serve the self-service app in compose (refs #68)
+- Run Vitest ahead of the production build to stop worker-start timeout (refs #68)
+- Cache the NuGet package store across the .NET jobs (refs #73)
+- Run Playwright from the prebuilt image instead of downloading browsers (refs #73)
 
 ### Chores
 - Add idempotent Gitea backlog seeder
 - Remove bootstrap scripts from main (#35)
+- Contributor workflow — templates, git-cliff, gitea-workflow doc (closes #31) (#38)
 
 ### Documentation
 - Split S-00 into sub-slices (refs #1) (#33)
+- MkDocs scaffold + ADR-0001 + README quickstart (closes #32) (#39)
+- Tighten gitea-actions-gotchas, add local compose (refs #30)
+- ADR-0008 read projection store + demo note for the event path (refs #7)
+- Demo note for submitting a registration (S-05) (refs #6)
+- Demo note for the BFF front door (S-07) (refs #8)
+- Split S-08 into S-08a-d (refs #65)
+- Frontend-decisions + demo note for S-08a (refs #65)
+- Record the orval generator choice (refs #66)
+- Record NL DS + DigiD decisions and demo note (refs #67)
+- Serving/e2e decisions + walking-skeleton demo note (refs #68)
 
 ### Features
 - Placeholder BFF + /health endpoint (closes #28) (#34)
 - Containerize BFF + compose-up smoke (closes #29) (#36)
+- OpenZaak + Postgres + Redis up in compose (refs #10) (#40)
+- Seed BIG catalogus + JWT client for OpenZaak (refs #2) (#41)
+- Open Notificaties up + shared network (closes #2) (#42)
+- Keycloak with four mock realms (closes #3) (#43)
+- Flowable + registratie.bpmn external task (closes #4) (#44)
+- ACL skeleton — OpenZaak default-fill (refs #5) (#45)
+- Add bind-mount local compose for no-make/Windows dev (refs #30)
+- Publish the BIG zaaktype on demand via OZ_PUBLISH (refs #46)
+- Wire OpenZaak → Open Notificaties notifications (refs #56)
+- Project zaak-created notifications into the read projection (refs #7)
+- Persist the read projection and expose webhook + read APIs (refs #7)
+- Enforce the callback bearer before reading the body (refs #7)
+- Implement the Registration aggregate invariants (refs #6)
+- Implement SubmitRegistration and OpenZaakWorker (refs #6)
+- Implement the Flowable Workflow Client and ACL client (refs #6)
+- Expose POST /registrations and the read endpoint (refs #6)
+- Implement self-service submit and openbaar lookup (refs #8)
+- Committed OpenAPI contract + drift guard (refs #8)
+- Self-service portal placeholder page (refs #65)
+- Expose the generated BFF client + repeatable generate target (refs #66)
+- Implement the DigiD registration submit page (refs #67)
+- Runtime config + nginx serve/proxy image (refs #68)
+- Surface submit failures with a retryable alert (refs #68)
+- One citizen reference across self-service and the openbaar register (#79)
+
+### Other
+- Openbaar Register portal — public lookup (#76)
+- Approval flow — temp admin endpoint + status transition to projection (#77)
+
+### Refactor
+- Bake config via dockerfile_inline, drop Dockerfile files (refs #30)
+- Use upstream images verbatim, seed config via docker cp (refs #30)
+- One verify-stack stage for all live-stack checks (closes #58) (refs #46 #56)
+
+### Tests
+- BDD acceptance scenario for opening a zaak (closes #5) (#49)
+- Kill surviving mutants — assert CRS headers, guards, error paths, JWT claims (refs #47)
+- Add Stryker config + mutation make target recording the 95% baseline (refs #47)
+- Integration test opens a real zaak against OpenZaak (refs #46)
+- Verify-notifications smoke + CI job for the OZ→NRC path (refs #56)
+- Project zaak-created notifications into the read projection (refs #7)
+- Ratchet projector mutation baseline to 100% (refs #7)
+- Registration aggregate invariants (refs #6)
+- SubmitRegistration + OpenZaakWorker use cases (refs #6)
+- Workflow Client, ACL client, store and job processor (refs #6)
+- Acceptance scenario for submitting a registration (refs #6)
+- Mutation baseline 90 (achieved 97.7%) + CI/Makefile wiring (refs #6)
+- Endpoints, JWT auth and public-safe projection (refs #8)
+- Acceptance scenario for BFF access (valid/invalid tokens) (refs #8)
+- Self-service portal placeholder renders (refs #65)
+- Generated BFF client is exposed and calls the endpoints (refs #66)
+- DigiD-guarded registration submit page (refs #67)
+- Walking-skeleton Playwright happy path + verify-e2e lane (refs #68)
+- Submit surfaces BFF failures instead of swallowing them (refs #68)
+- Guard that the DigiD token attaches to relative BFF calls (refs #68)
 

Makefile

@@ -10,7 +10,7 @@ COMPOSE    := infra/docker-compose.yml
 # Long-running services with a healthcheck — the smoke polls these for readiness
 # (infra/wait-healthy.sh). One-shot init jobs (oz-init, nrc-init, flowable-init)
 # are not polled; they only need to have run. See docs/runbooks/gitea-actions-gotchas.md.
-WAIT_SVCS  := openzaak nrc-web acl bff domain event-subscriber projection-api
+WAIT_SVCS  := openzaak nrc-web acl bff domain event-subscriber projection-api self-service openbaar behandel beheer
 # Config files (OpenZaak data.yaml, Keycloak realms, Flowable BPMN) are streamed
 # into external named volumes via `docker cp` (infra/seed-config.sh) instead of
 # bind-mounted, because bind mounts don't reach sibling containers on the
@@ -43,16 +43,23 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif
 
-.PHONY: ci lint build unit mutation frontend integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-notifications smoke up down local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down help
+.PHONY: ci lint build unit mutation frontend integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-observability verify-tracing verify-metrics verify-notifications smoke up down local verify-local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down help
 
 ## ci: run the full pipeline — lint, build, unit, mutation, frontend, verify (mirrors Gitea Actions)
 ## `verify` is the live-stack stage (full stack up once → ACL + notification checks).
 ci: lint build unit mutation frontend verify
 
 ## frontend: install deps and run the Nx lint/test/build for the portals (pnpm + Node required)
+# Tests run in their own phase, ahead of the build. The @angular/build:unit-test
+# (Vitest) runner spawns a worker with a hard-coded 60s/90s startup timeout that is
+# not configurable. When the ~5min production build shares the run-many pool, it
+# starves that worker of CPU on constrained CI runners and Vitest fails with
+# "Timeout waiting for worker to respond". Splitting the phases keeps tests off the
+# heavy build's back so the worker starts well inside its window.
 frontend:
 	pnpm install --frozen-lockfile
-	pnpm nx run-many -t lint test build
+	pnpm nx run-many -t lint test
+	pnpm nx run-many -t build
 
 ## lint: verify formatting (no changes)
 lint:
@@ -107,6 +114,11 @@ local:
 	docker compose -f $(LOCAL_COMPOSE) up -d --build
 	WAIT_TIMEOUT=420 bash infra/wait-healthy.sh $(WAIT_SVCS)
 
+## verify-local: acceptance check for the local stack (S-B04) — a fresh `make local` completes the
+## whole flow (zaaktype seeded + DMN deployed + NRC abonnement) with NO manual seeding.
+verify-local:
+	bash infra/run-local-flow-check.sh
+
 ## local-down: stop and remove the bind-mount stack
 local-down:
 	docker compose -f $(LOCAL_COMPOSE) down --volumes
@@ -153,6 +165,26 @@ verify-domain:
 verify-bff:
 	bash infra/run-bff-check.sh
 
+## verify-e2e: walking-skeleton Playwright e2e (S-08d) against the up stack — DigiD login →
+## submit → confirmation, driven inside the compose network.
+verify-e2e:
+	bash infra/run-e2e-check.sh
+
+## verify-observability: assert the observability backplane (Grafana + provisioned Tempo &
+## Prometheus datasources) is live, against the already-running stack (S-16a).
+verify-observability:
+	bash infra/run-observability-check.sh
+
+## verify-tracing: assert one connected distributed trace spans the .NET services in Tempo
+## (S-16b), against the already-running stack.
+verify-tracing:
+	bash infra/run-tracing-check.sh
+
+## verify-metrics: assert the services expose /metrics and Prometheus scrapes the golden
+## signals (S-16c), against the already-running stack.
+verify-metrics:
+	bash infra/run-metrics-check.sh
+
 ## verify: local mirror of the CI verify-stack job — full stack up once, all checks,
 ## tear down (always). For fast single-concern local iteration use `integration`
 ## (oz-only) or `verify-notifications` (oz+nrc) instead.
@@ -165,7 +197,8 @@ verify:
 	    && bash infra/run-notification-check.sh \
 	    && bash infra/run-projection-check.sh \
 	    && bash infra/run-domain-check.sh \
-	    && bash infra/run-bff-check.sh || rc=$$?; \
+	    && bash infra/run-bff-check.sh \
+	    && bash infra/run-e2e-check.sh || rc=$$?; \
 	  docker compose -f $(COMPOSE) down --volumes >/dev/null 2>&1; \
 	  docker volume rm -f $(CFG_VOLS) >/dev/null 2>&1; \
 	  exit $$rc'

apps/behandel/Dockerfile

@@ -0,0 +1,27 @@
+# Multi-stage build for the behandel portal (Angular → nginx).
+# Build context is the repo root (the app needs the pnpm workspace + libs). See infra/docker-compose.yml.
+FROM node:24-slim AS build
+WORKDIR /src
+RUN corepack enable && corepack prepare pnpm@11.5.2 --activate
+
+# Restore first (cached unless the manifests change).
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml nx.json tsconfig.base.json eslint.config.mjs ./
+RUN pnpm install --frozen-lockfile
+
+# Sources (only what the app + its libs need).
+COPY apps/behandel apps/behandel
+COPY libs libs
+RUN pnpm nx build behandel
+
+FROM nginx:1.27-alpine AS runtime
+COPY apps/behandel/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /src/dist/apps/behandel/browser /usr/share/nginx/html
+# Compose-time OIDC config: the browser (Playwright, on the compose network) reaches Keycloak by
+# service name, so the token issuer matches the BFF's medewerker authority (host-consistent, ADR-0013).
+RUN printf '{ "authority": "http://keycloak:8080/realms/medewerker" }\n' > /usr/share/nginx/html/config.json
+# Make the reverse-proxy resolver engine-portable (Docker 127.0.0.11 vs podman aardvark); runs from
+# the nginx image's /docker-entrypoint.d before nginx starts.
+COPY apps/portal-nginx-resolver.sh /docker-entrypoint.d/40-resolver.sh
+RUN chmod +x /docker-entrypoint.d/40-resolver.sh
+
+EXPOSE 80

apps/behandel/eslint.config.mjs

@@ -0,0 +1,34 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'app',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'app',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    // Override or add rules here
+    rules: {},
+  },
+];

apps/behandel/nginx.conf

@@ -0,0 +1,24 @@
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Resolve the BFF via Docker's embedded DNS at request time (variable proxy_pass), so nginx starts
+  # even before the BFF is up and picks up restarts — instead of failing to load the config.
+  resolver 127.0.0.11 ipv6=off valid=30s;
+
+  # Same-origin API: proxy the behandel endpoint group to the bff service. The api-client uses
+  # relative URLs, so the browser calls this origin and nginx forwards to the BFF — no CORS, and the
+  # medewerker token (same-origin) is attached by the app's interceptor (ADR-0013).
+  location /behandel/ {
+    set $bff http://bff:8080;
+    proxy_pass $bff;
+    proxy_set_header Host $host;
+  }
+
+  # SPA fallback — Angular client-side routing.
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

apps/behandel/project.json

@@ -0,0 +1,80 @@
+{
+  "name": "behandel",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "prefix": "app",
+  "sourceRoot": "apps/behandel/src",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@angular/build:application",
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "options": {
+        "outputPath": "dist/apps/behandel",
+        "browser": "apps/behandel/src/main.ts",
+        "tsConfig": "apps/behandel/tsconfig.app.json",
+        "assets": [
+          {
+            "glob": "**/*",
+            "input": "apps/behandel/public"
+          }
+        ],
+        "styles": ["apps/behandel/src/styles.css"]
+      },
+      "configurations": {
+        "production": {
+          "budgets": [
+            {
+              "type": "initial",
+              "maximumWarning": "1mb",
+              "maximumError": "2mb"
+            },
+            {
+              "type": "anyComponentStyle",
+              "maximumWarning": "4kb",
+              "maximumError": "8kb"
+            }
+          ],
+          "outputHashing": "all"
+        },
+        "development": {
+          "optimization": false,
+          "extractLicenses": false,
+          "sourceMap": true
+        }
+      }
+    },
+    "serve": {
+      "continuous": true,
+      "executor": "@angular/build:dev-server",
+      "defaultConfiguration": "development",
+      "configurations": {
+        "production": {
+          "buildTarget": "behandel:build:production"
+        },
+        "development": {
+          "buildTarget": "behandel:build:development"
+        }
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "test": {
+      "executor": "@angular/build:unit-test",
+      "options": {
+        "watch": false
+      }
+    },
+    "serve-static": {
+      "continuous": true,
+      "executor": "@nx/web:file-server",
+      "options": {
+        "buildTarget": "behandel:build",
+        "staticFilePath": "dist/apps/behandel/browser",
+        "spa": true
+      }
+    }
+  }
+}

apps/behandel/public/config.json

@@ -0,0 +1,3 @@
+{
+  "authority": "http://localhost:8180/realms/medewerker"
+}

apps/behandel/src/app/app.config.spec.ts

@@ -0,0 +1,73 @@
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import { BffApiV1Service } from 'api-client';
+import { authInterceptor } from 'auth';
+import { AbstractSecurityStorage, ConfigurationService } from 'angular-auth-oidc-client';
+import { SECURE_API_ROUTES } from './app.config';
+
+// Guards the medewerker token wiring end-to-end. The api-client calls the BFF with RELATIVE URLs, and
+// the angular-auth-oidc-client interceptor attaches the token only when `req.url` starts with a
+// configured secureRoute. A regression to an absolute origin makes the relative URL never match, so
+// the behandel calls go out unauthenticated and the BFF answers 401. This drives the REAL interceptor
+// and the REAL api-client against the REAL production route value (SECURE_API_ROUTES); only the config
+// source and token storage are faked, so the assertion turns on the actual route-matching.
+describe('behandel medewerker token wiring', () => {
+  let http: HttpTestingController;
+  let bff: BffApiV1Service;
+  const token = 'medewerker-access-token';
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(withInterceptors([authInterceptor()])),
+        provideHttpClientTesting(),
+        {
+          provide: ConfigurationService,
+          useValue: {
+            hasAtLeastOneConfig: () => true,
+            getAllConfigurations: () => [{ configId: 'medewerker', secureRoutes: SECURE_API_ROUTES }],
+          },
+        },
+        {
+          // A signed-in session: the storage the interceptor's token lookup reads from.
+          provide: AbstractSecurityStorage,
+          useValue: {
+            read: () => JSON.stringify({ authzData: token, authnResult: { id_token: 'id-token' } }),
+            write: () => undefined,
+            remove: () => undefined,
+            clear: () => undefined,
+          },
+        },
+      ],
+    });
+    http = TestBed.inject(HttpTestingController);
+    bff = TestBed.inject(BffApiV1Service);
+  });
+
+  afterEach(() => http.verify());
+
+  it('attaches the bearer token to the relative werkbak call', () => {
+    bff.getBehandelWerkbak().subscribe();
+
+    const req = http.expectOne('/behandel/werkbak');
+    expect(req.request.headers.get('Authorization')).toBe(`Bearer ${token}`);
+    req.flush([]);
+  });
+
+  it('attaches the bearer token to the relative decide call', () => {
+    bff.postBehandelRegistrationsIdDecide('reg-1', { besluit: 'goedkeuren' }).subscribe();
+
+    const req = http.expectOne('/behandel/registrations/reg-1/decide');
+    expect(req.request.headers.get('Authorization')).toBe(`Bearer ${token}`);
+    req.flush(null);
+  });
+
+  it('leaves the anonymous openbaar register call unauthenticated', () => {
+    bff.getOpenbaarRegister().subscribe();
+
+    const req = http.expectOne((r) => r.url === '/openbaar/register');
+    expect(req.request.headers.has('Authorization')).toBe(false);
+    req.flush([]);
+  });
+});

apps/behandel/src/app/app.config.ts

@@ -0,0 +1,39 @@
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { authInterceptor, provideMedewerkerAuth } from 'auth';
+import { appRoutes } from './app.routes';
+
+/** Environment-specific settings fetched from /config.json at startup (see main.ts). */
+export interface RuntimeConfig {
+  /** The Keycloak `medewerker` realm issuer as the browser reaches it (dev: localhost; compose: keycloak:8080). */
+  authority: string;
+}
+
+/**
+ * Route prefixes whose requests carry the medewerker token. These MUST match the **relative** URLs
+ * the api-client actually calls (same-origin via the nginx proxy) — the interceptor matches on
+ * `req.url`, which stays relative, so an absolute origin would never match and the token would go
+ * unattached. Only `/behandel/` is secured; the app calls no other endpoint group.
+ */
+export const SECURE_API_ROUTES = ['/behandel/'];
+
+/**
+ * Build the app providers from runtime config. `redirectUrl` is the app's own origin (where Keycloak
+ * redirects back). `secureRoutes` uses {@link SECURE_API_ROUTES} — relative prefixes, not the origin.
+ */
+export function appConfig(runtime: RuntimeConfig): ApplicationConfig {
+  const origin = typeof window !== 'undefined' ? window.location.origin : '/';
+  return {
+    providers: [
+      provideBrowserGlobalErrorListeners(),
+      provideRouter(appRoutes),
+      provideHttpClient(withInterceptors([authInterceptor()])),
+      provideMedewerkerAuth({
+        authority: runtime.authority,
+        redirectUrl: origin,
+        secureRoutes: SECURE_API_ROUTES,
+      }),
+    ],
+  };
+}

apps/behandel/src/app/app.html

@@ -0,0 +1 @@
+<router-outlet></router-outlet>

apps/behandel/src/app/app.routes.ts

@@ -0,0 +1,7 @@
+import { Route } from '@angular/router';
+import { authenticatedGuard } from 'auth';
+import { WerkbakPage } from './werkbak/werkbak-page';
+
+export const appRoutes: Route[] = [
+  { path: '', component: WerkbakPage, canActivate: [authenticatedGuard] },
+];

apps/behandel/src/app/app.spec.ts

@@ -0,0 +1,15 @@
+import { provideRouter } from '@angular/router';
+import { render, screen } from '@testing-library/angular';
+import { App } from './app';
+
+describe('App', () => {
+  it('renders the router outlet shell', async () => {
+    const { container } = await render(App, {
+      providers: [provideRouter([])],
+    });
+
+    // The shell is a thin host for routed pages (the WerkbakPage owns the heading).
+    expect(container.querySelector('router-outlet')).toBeTruthy();
+    expect(screen).toBeTruthy();
+  });
+});

apps/behandel/src/app/app.ts

@@ -0,0 +1,12 @@
+import { Component } from '@angular/core';
+import { RouterModule } from '@angular/router';
+
+@Component({
+  imports: [RouterModule],
+  selector: 'app-root',
+  templateUrl: './app.html',
+  styleUrl: './app.css',
+})
+export class App {
+  protected title = 'behandel';
+}

apps/behandel/src/app/werkbak/werkbak-page.html

@@ -0,0 +1,64 @@
+<main utrecht-document class="utrecht-theme">
+  <utrecht-article>
+    <utrecht-heading-1>Werkbak</utrecht-heading-1>
+    <p utrecht-paragraph>
+      Registraties die wachten op beoordeling. Keur elke registratie goed of wijs deze af.
+    </p>
+
+    @if (loading()) {
+      <p utrecht-paragraph role="status">Bezig met laden…</p>
+    } @else if (failed()) {
+      <p utrecht-paragraph role="alert">
+        Kon de werkbak niet laden. Controleer of je als behandelaar bent ingelogd en probeer het
+        opnieuw.
+      </p>
+    } @else if (loaded() && items().length === 0) {
+      <p utrecht-paragraph role="status">De werkbak is leeg.</p>
+    } @else if (items().length > 0) {
+      <table utrecht-table>
+        <caption>
+          Registraties in behandeling
+        </caption>
+        <thead>
+          <tr>
+            <th scope="col">Referentie</th>
+            <th scope="col">BSN</th>
+            <th scope="col">Status</th>
+            <th scope="col">Actie</th>
+          </tr>
+        </thead>
+        <tbody>
+          @for (item of items(); track item.registrationId) {
+            <tr>
+              <td>{{ item.registrationId }}</td>
+              <td>{{ item.bsn }}</td>
+              <td>{{ item.status }}</td>
+              <td>
+                <button
+                  utrecht-button
+                  appearance="primary-action-button"
+                  type="button"
+                  [attr.aria-label]="'Goedkeuren ' + item.registrationId"
+                  [disabled]="deciding() === item.registrationId"
+                  (click)="decide(item.registrationId, 'goedkeuren')"
+                >
+                  Goedkeuren
+                </button>
+                <button
+                  utrecht-button
+                  appearance="secondary-action-button"
+                  type="button"
+                  [attr.aria-label]="'Afwijzen ' + item.registrationId"
+                  [disabled]="deciding() === item.registrationId"
+                  (click)="decide(item.registrationId, 'afwijzen')"
+                >
+                  Afwijzen
+                </button>
+              </td>
+            </tr>
+          }
+        </tbody>
+      </table>
+    }
+  </utrecht-article>
+</main>

apps/behandel/src/app/werkbak/werkbak-page.spec.ts

@@ -0,0 +1,110 @@
+import { signal } from '@angular/core';
+import { fireEvent, render, screen } from '@testing-library/angular';
+import { of, throwError } from 'rxjs';
+import { BffApiV1Service, type WerkbakItem } from 'api-client';
+import { AuthService } from 'auth';
+import { axe } from 'vitest-axe';
+import { WerkbakPage } from './werkbak-page';
+
+const sample: WerkbakItem[] = [
+  { registrationId: 'reg-1', bsn: '123456782', status: 'InBehandeling' },
+  { registrationId: 'reg-2', bsn: '111222333', status: 'InBehandeling' },
+];
+
+class FakeAuth extends AuthService {
+  readonly isAuthenticated = signal(true);
+  readonly bsn = signal<string | undefined>(undefined);
+  override readonly roles = signal<readonly string[]>(['behandelaar']);
+  login(): void {
+    /* not exercised here */
+  }
+  logout(): void {
+    /* spied in tests */
+  }
+}
+
+function setup(
+  overrides: {
+    getBehandelWerkbak?: ReturnType<typeof vi.fn>;
+    postBehandelRegistrationsIdDecide?: ReturnType<typeof vi.fn>;
+  } = {},
+) {
+  const getBehandelWerkbak =
+    overrides.getBehandelWerkbak ?? vi.fn().mockReturnValue(of(sample));
+  const postBehandelRegistrationsIdDecide =
+    overrides.postBehandelRegistrationsIdDecide ?? vi.fn().mockReturnValue(of(undefined));
+  return {
+    getBehandelWerkbak,
+    postBehandelRegistrationsIdDecide,
+    providers: [
+      {
+        provide: BffApiV1Service,
+        useValue: { getBehandelWerkbak, postBehandelRegistrationsIdDecide },
+      },
+      { provide: AuthService, useClass: FakeAuth },
+    ],
+  };
+}
+
+describe('WerkbakPage', () => {
+  it('lists the registrations awaiting beoordeling on open', async () => {
+    const { getBehandelWerkbak, providers } = setup();
+    await render(WerkbakPage, { providers });
+
+    expect(getBehandelWerkbak).toHaveBeenCalled();
+    expect(await screen.findByText('reg-1')).toBeTruthy();
+    expect(screen.getByText('123456782')).toBeTruthy();
+    expect(screen.getByText('reg-2')).toBeTruthy();
+  });
+
+  it('approves a registration (goedkeuren) and refreshes the werkbak', async () => {
+    const { getBehandelWerkbak, postBehandelRegistrationsIdDecide, providers } = setup();
+    await render(WerkbakPage, { providers });
+
+    fireEvent.click((await screen.findAllByRole('button', { name: /goedkeuren/i }))[0]);
+
+    expect(postBehandelRegistrationsIdDecide).toHaveBeenCalledWith('reg-1', {
+      besluit: 'goedkeuren',
+    });
+    // Reloaded after the decision: once on open, once after deciding.
+    expect(getBehandelWerkbak).toHaveBeenCalledTimes(2);
+  });
+
+  it('rejects a registration (afwijzen) via the decide endpoint', async () => {
+    const { postBehandelRegistrationsIdDecide, providers } = setup();
+    await render(WerkbakPage, { providers });
+
+    fireEvent.click((await screen.findAllByRole('button', { name: /afwijzen/i }))[0]);
+
+    expect(postBehandelRegistrationsIdDecide).toHaveBeenCalledWith('reg-1', {
+      besluit: 'afwijzen',
+    });
+  });
+
+  it('shows an empty state when the werkbak has no items', async () => {
+    const { providers } = setup({ getBehandelWerkbak: vi.fn().mockReturnValue(of([])) });
+    await render(WerkbakPage, { providers });
+
+    expect(await screen.findByText(/werkbak is leeg/i)).toBeTruthy();
+  });
+
+  it('surfaces a load failure instead of swallowing it', async () => {
+    const { providers } = setup({
+      getBehandelWerkbak: vi.fn().mockReturnValue(throwError(() => new Error('403'))),
+    });
+    await render(WerkbakPage, { providers });
+
+    expect(await screen.findByText(/kon de werkbak niet laden/i)).toBeTruthy();
+  });
+
+  it('has no WCAG 2.1 AA violations', async () => {
+    document.documentElement.lang = 'nl';
+    const { container } = await render(WerkbakPage, { providers: setup().providers });
+
+    const results = await axe(container, {
+      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] },
+    });
+
+    expect(results.violations).toEqual([]);
+  });
+});

apps/behandel/src/app/werkbak/werkbak-page.ts

@@ -0,0 +1,65 @@
+import { Component, inject, signal } from '@angular/core';
+import { BffApiV1Service, type WerkbakItem } from 'api-client';
+import { UtrechtComponentsModule } from 'ui';
+
+/** The two decisions a behandelaar can make; the BFF validates these exact values (ADR-0013). */
+type Besluit = 'goedkeuren' | 'afwijzen';
+
+/**
+ * The behandel werkbak: a signed-in behandelaar sees the registrations awaiting beoordeling (the open
+ * Flowable `Beoordelen` tasks, read through the domain) and decides each — goedkeuren or afwijzen. A
+ * decision posts to the BFF, which applies the domain transition and completes the workflow task
+ * (ADR-0013; S-12). After a decision the werkbak refreshes so the handled item drops off the list.
+ */
+@Component({
+  selector: 'app-werkbak-page',
+  imports: [UtrechtComponentsModule],
+  templateUrl: './werkbak-page.html',
+})
+export class WerkbakPage {
+  private readonly bff = inject(BffApiV1Service);
+
+  protected readonly items = signal<WerkbakItem[]>([]);
+  protected readonly loading = signal(false);
+  protected readonly loaded = signal(false);
+  protected readonly failed = signal(false);
+  protected readonly deciding = signal<string | undefined>(undefined);
+
+  constructor() {
+    this.load();
+  }
+
+  load(): void {
+    this.loading.set(true);
+    this.failed.set(false);
+    this.bff.getBehandelWerkbak().subscribe({
+      next: (rows: WerkbakItem[]) => {
+        this.items.set(rows);
+        this.loading.set(false);
+        this.loaded.set(true);
+      },
+      // Surface the failure (e.g. 403 for a non-behandelaar) instead of swallowing it.
+      error: () => {
+        this.items.set([]);
+        this.loading.set(false);
+        this.loaded.set(true);
+        this.failed.set(true);
+      },
+    });
+  }
+
+  decide(registrationId: string, besluit: Besluit): void {
+    this.deciding.set(registrationId);
+    this.bff.postBehandelRegistrationsIdDecide(registrationId, { besluit }).subscribe({
+      // Refresh so the decided registration drops off the werkbak (its task is now completed).
+      next: () => {
+        this.deciding.set(undefined);
+        this.load();
+      },
+      error: () => {
+        this.deciding.set(undefined);
+        this.failed.set(true);
+      },
+    });
+  }
+}

apps/behandel/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="nl">
+  <head>
+    <meta charset="utf-8" />
+    <title>Behandelportaal BIG-register</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="favicon.ico" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

apps/behandel/src/main.ts

@@ -0,0 +1,10 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+import { appConfig, type RuntimeConfig } from './app/app.config';
+
+// Load environment config before bootstrap so the OIDC authority is set per environment
+// (dev: localhost; compose: keycloak:8080) from a single build — 12-factor (S-08d).
+fetch('config.json')
+  .then((response) => response.json() as Promise<RuntimeConfig>)
+  .then((config) => bootstrapApplication(App, appConfig(config)))
+  .catch((err) => console.error(err));

apps/behandel/src/styles.css

@@ -0,0 +1,2 @@
+/* NL Design System theme — Utrecht design tokens (docs/frontend-decisions.md). */
+@import '@utrecht/design-tokens/dist/index.css';

apps/behandel/tsconfig.app.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}

apps/behandel/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "target": "es2022",
+    "moduleResolution": "bundler",
+    "emitDecoratorMetadata": false,
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

apps/behandel/tsconfig.spec.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"]
+}

apps/beheer/Dockerfile

@@ -0,0 +1,27 @@
+# Multi-stage build for the beheer portal (Angular → nginx).
+# Build context is the repo root (the app needs the pnpm workspace + libs). See infra/docker-compose.yml.
+FROM node:24-slim AS build
+WORKDIR /src
+RUN corepack enable && corepack prepare pnpm@11.5.2 --activate
+
+# Restore first (cached unless the manifests change).
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml nx.json tsconfig.base.json eslint.config.mjs ./
+RUN pnpm install --frozen-lockfile
+
+# Sources (only what the app + its libs need).
+COPY apps/beheer apps/beheer
+COPY libs libs
+RUN pnpm nx build beheer
+
+FROM nginx:1.27-alpine AS runtime
+COPY apps/beheer/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /src/dist/apps/beheer/browser /usr/share/nginx/html
+# Compose-time OIDC config: the browser (Playwright, on the compose network) reaches Keycloak by
+# service name, so the token issuer matches the BFF's medewerker authority (host-consistent, ADR-0013).
+RUN printf '{ "authority": "http://keycloak:8080/realms/medewerker" }\n' > /usr/share/nginx/html/config.json
+# Make the reverse-proxy resolver engine-portable (Docker 127.0.0.11 vs podman aardvark); runs from
+# the nginx image's /docker-entrypoint.d before nginx starts.
+COPY apps/portal-nginx-resolver.sh /docker-entrypoint.d/40-resolver.sh
+RUN chmod +x /docker-entrypoint.d/40-resolver.sh
+
+EXPOSE 80

apps/beheer/eslint.config.mjs

@@ -0,0 +1,34 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'app',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'app',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    // Override or add rules here
+    rules: {},
+  },
+];

apps/beheer/nginx.conf

@@ -0,0 +1,24 @@
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Resolve the BFF via Docker's embedded DNS at request time (variable proxy_pass), so nginx starts
+  # even before the BFF is up and picks up restarts — instead of failing to load the config.
+  resolver 127.0.0.11 ipv6=off valid=30s;
+
+  # Same-origin API: proxy the beheer endpoint group to the bff service. The api-client uses
+  # relative URLs, so the browser calls this origin and nginx forwards to the BFF — no CORS, and the
+  # medewerker token (same-origin) is attached by the app's interceptor (ADR-0013).
+  location /beheer/ {
+    set $bff http://bff:8080;
+    proxy_pass $bff;
+    proxy_set_header Host $host;
+  }
+
+  # SPA fallback — Angular client-side routing.
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

apps/beheer/project.json

@@ -0,0 +1,80 @@
+{
+  "name": "beheer",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "prefix": "app",
+  "sourceRoot": "apps/beheer/src",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@angular/build:application",
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "options": {
+        "outputPath": "dist/apps/beheer",
+        "browser": "apps/beheer/src/main.ts",
+        "tsConfig": "apps/beheer/tsconfig.app.json",
+        "assets": [
+          {
+            "glob": "**/*",
+            "input": "apps/beheer/public"
+          }
+        ],
+        "styles": ["apps/beheer/src/styles.css"]
+      },
+      "configurations": {
+        "production": {
+          "budgets": [
+            {
+              "type": "initial",
+              "maximumWarning": "1mb",
+              "maximumError": "2mb"
+            },
+            {
+              "type": "anyComponentStyle",
+              "maximumWarning": "4kb",
+              "maximumError": "8kb"
+            }
+          ],
+          "outputHashing": "all"
+        },
+        "development": {
+          "optimization": false,
+          "extractLicenses": false,
+          "sourceMap": true
+        }
+      }
+    },
+    "serve": {
+      "continuous": true,
+      "executor": "@angular/build:dev-server",
+      "defaultConfiguration": "development",
+      "configurations": {
+        "production": {
+          "buildTarget": "beheer:build:production"
+        },
+        "development": {
+          "buildTarget": "beheer:build:development"
+        }
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "test": {
+      "executor": "@angular/build:unit-test",
+      "options": {
+        "watch": false
+      }
+    },
+    "serve-static": {
+      "continuous": true,
+      "executor": "@nx/web:file-server",
+      "options": {
+        "buildTarget": "beheer:build",
+        "staticFilePath": "dist/apps/beheer/browser",
+        "spa": true
+      }
+    }
+  }
+}

apps/beheer/public/config.json

@@ -0,0 +1,3 @@
+{
+  "authority": "http://localhost:8180/realms/medewerker"
+}

apps/beheer/src/app/app.config.spec.ts

@@ -0,0 +1,65 @@
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import { BffApiV1Service } from 'api-client';
+import { authInterceptor } from 'auth';
+import { AbstractSecurityStorage, ConfigurationService } from 'angular-auth-oidc-client';
+import { SECURE_API_ROUTES } from './app.config';
+
+// Guards the medewerker token wiring end-to-end. The api-client calls the BFF with RELATIVE URLs, and
+// the angular-auth-oidc-client interceptor attaches the token only when `req.url` starts with a
+// configured secureRoute. A regression to an absolute origin makes the relative URL never match, so
+// the beheer calls go out unauthenticated and the BFF answers 401. This drives the REAL interceptor
+// and the REAL api-client against the REAL production route value (SECURE_API_ROUTES); only the config
+// source and token storage are faked, so the assertion turns on the actual route-matching.
+describe('beheer medewerker token wiring', () => {
+  let http: HttpTestingController;
+  let bff: BffApiV1Service;
+  const token = 'medewerker-access-token';
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(withInterceptors([authInterceptor()])),
+        provideHttpClientTesting(),
+        {
+          provide: ConfigurationService,
+          useValue: {
+            hasAtLeastOneConfig: () => true,
+            getAllConfigurations: () => [{ configId: 'medewerker', secureRoutes: SECURE_API_ROUTES }],
+          },
+        },
+        {
+          // A signed-in session: the storage the interceptor's token lookup reads from.
+          provide: AbstractSecurityStorage,
+          useValue: {
+            read: () => JSON.stringify({ authzData: token, authnResult: { id_token: 'id-token' } }),
+            write: () => undefined,
+            remove: () => undefined,
+            clear: () => undefined,
+          },
+        },
+      ],
+    });
+    http = TestBed.inject(HttpTestingController);
+    bff = TestBed.inject(BffApiV1Service);
+  });
+
+  afterEach(() => http.verify());
+
+  it('attaches the bearer token to the relative catalogus call', () => {
+    bff.getBeheerCatalogiZaaktypen().subscribe();
+
+    const req = http.expectOne('/beheer/catalogi/zaaktypen');
+    expect(req.request.headers.get('Authorization')).toBe(`Bearer ${token}`);
+    req.flush([]);
+  });
+
+  it('leaves the anonymous openbaar register call unauthenticated', () => {
+    bff.getOpenbaarRegister().subscribe();
+
+    const req = http.expectOne((r) => r.url === '/openbaar/register');
+    expect(req.request.headers.has('Authorization')).toBe(false);
+    req.flush([]);
+  });
+});

apps/beheer/src/app/app.config.ts

@@ -0,0 +1,39 @@
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { authInterceptor, provideMedewerkerAuth } from 'auth';
+import { appRoutes } from './app.routes';
+
+/** Environment-specific settings fetched from /config.json at startup (see main.ts). */
+export interface RuntimeConfig {
+  /** The Keycloak `medewerker` realm issuer as the browser reaches it (dev: localhost; compose: keycloak:8080). */
+  authority: string;
+}
+
+/**
+ * Route prefixes whose requests carry the medewerker token. These MUST match the **relative** URLs
+ * the api-client actually calls (same-origin via the nginx proxy) — the interceptor matches on
+ * `req.url`, which stays relative, so an absolute origin would never match and the token would go
+ * unattached. Only `/beheer/` is secured; the app calls no other endpoint group.
+ */
+export const SECURE_API_ROUTES = ['/beheer/'];
+
+/**
+ * Build the app providers from runtime config. `redirectUrl` is the app's own origin (where Keycloak
+ * redirects back). `secureRoutes` uses {@link SECURE_API_ROUTES} — relative prefixes, not the origin.
+ */
+export function appConfig(runtime: RuntimeConfig): ApplicationConfig {
+  const origin = typeof window !== 'undefined' ? window.location.origin : '/';
+  return {
+    providers: [
+      provideBrowserGlobalErrorListeners(),
+      provideRouter(appRoutes),
+      provideHttpClient(withInterceptors([authInterceptor()])),
+      provideMedewerkerAuth({
+        authority: runtime.authority,
+        redirectUrl: origin,
+        secureRoutes: SECURE_API_ROUTES,
+      }),
+    ],
+  };
+}

apps/beheer/src/app/app.html

@@ -0,0 +1 @@
+<router-outlet></router-outlet>

apps/beheer/src/app/app.routes.ts

@@ -0,0 +1,7 @@
+import { Route } from '@angular/router';
+import { authenticatedGuard } from 'auth';
+import { CatalogusPage } from './catalogus/catalogus-page';
+
+export const appRoutes: Route[] = [
+  { path: '', component: CatalogusPage, canActivate: [authenticatedGuard] },
+];

apps/beheer/src/app/app.spec.ts

@@ -0,0 +1,15 @@
+import { provideRouter } from '@angular/router';
+import { render, screen } from '@testing-library/angular';
+import { App } from './app';
+
+describe('App', () => {
+  it('renders the router outlet shell', async () => {
+    const { container } = await render(App, {
+      providers: [provideRouter([])],
+    });
+
+    // The shell is a thin host for routed pages (the CatalogusPage owns the heading).
+    expect(container.querySelector('router-outlet')).toBeTruthy();
+    expect(screen).toBeTruthy();
+  });
+});

apps/beheer/src/app/app.ts

@@ -0,0 +1,12 @@
+import { Component } from '@angular/core';
+import { RouterModule } from '@angular/router';
+
+@Component({
+  imports: [RouterModule],
+  selector: 'app-root',
+  templateUrl: './app.html',
+  styleUrl: './app.css',
+})
+export class App {
+  protected title = 'beheer';
+}

apps/beheer/src/app/catalogus/catalogus-page.html

@@ -0,0 +1,40 @@
+<main utrecht-document class="utrecht-theme">
+  <utrecht-article>
+    <utrecht-heading-1>Catalogus</utrecht-heading-1>
+    <p utrecht-paragraph>
+      De gepubliceerde zaaktypen uit de ZTC-catalogus. Alleen-lezen — beheer van de default-fill volgt
+      in een latere slice.
+    </p>
+
+    @if (loading()) {
+      <p utrecht-paragraph role="status">Bezig met laden…</p>
+    } @else if (failed()) {
+      <p utrecht-paragraph role="alert">
+        Kon de catalogus niet laden. Controleer of je als beheerder bent ingelogd en probeer het
+        opnieuw.
+      </p>
+    } @else if (loaded() && items().length === 0) {
+      <p utrecht-paragraph role="status">De catalogus bevat geen gepubliceerde zaaktypen.</p>
+    } @else if (items().length > 0) {
+      <table utrecht-table>
+        <caption>
+          Gepubliceerde zaaktypen
+        </caption>
+        <thead>
+          <tr>
+            <th scope="col">Identificatie</th>
+            <th scope="col">Omschrijving</th>
+          </tr>
+        </thead>
+        <tbody>
+          @for (zaaktype of items(); track zaaktype.identificatie) {
+            <tr>
+              <td>{{ zaaktype.identificatie }}</td>
+              <td>{{ zaaktype.omschrijving }}</td>
+            </tr>
+          }
+        </tbody>
+      </table>
+    }
+  </utrecht-article>
+</main>

apps/beheer/src/app/catalogus/catalogus-page.spec.ts

@@ -0,0 +1,75 @@
+import { signal } from '@angular/core';
+import { render, screen } from '@testing-library/angular';
+import { of, throwError } from 'rxjs';
+import { BeheerZaaktype, BffApiV1Service } from 'api-client';
+import { AuthService } from 'auth';
+import { axe } from 'vitest-axe';
+import { CatalogusPage } from './catalogus-page';
+
+const sample: BeheerZaaktype[] = [
+  { identificatie: 'BIG-REGISTRATIE', omschrijving: 'BIG-registratie' },
+  { identificatie: 'BIG-HERREGISTRATIE', omschrijving: 'BIG-herregistratie' },
+];
+
+class FakeAuth extends AuthService {
+  readonly isAuthenticated = signal(true);
+  readonly bsn = signal<string | undefined>(undefined);
+  override readonly roles = signal<readonly string[]>(['beheerder']);
+  login(): void {
+    /* not exercised here */
+  }
+  logout(): void {
+    /* not exercised here */
+  }
+}
+
+function setup(overrides: { getBeheerCatalogiZaaktypen?: ReturnType<typeof vi.fn> } = {}) {
+  const getBeheerCatalogiZaaktypen =
+    overrides.getBeheerCatalogiZaaktypen ?? vi.fn().mockReturnValue(of(sample));
+  return {
+    getBeheerCatalogiZaaktypen,
+    providers: [
+      { provide: BffApiV1Service, useValue: { getBeheerCatalogiZaaktypen } },
+      { provide: AuthService, useClass: FakeAuth },
+    ],
+  };
+}
+
+describe('CatalogusPage', () => {
+  it('lists the published zaaktypen on open', async () => {
+    const { getBeheerCatalogiZaaktypen, providers } = setup();
+    await render(CatalogusPage, { providers });
+
+    expect(getBeheerCatalogiZaaktypen).toHaveBeenCalled();
+    expect(await screen.findByText('BIG-REGISTRATIE')).toBeTruthy();
+    expect(screen.getByText('BIG-registratie')).toBeTruthy();
+    expect(screen.getByText('BIG-HERREGISTRATIE')).toBeTruthy();
+  });
+
+  it('shows an empty state when the catalogus has no published zaaktypen', async () => {
+    const { providers } = setup({ getBeheerCatalogiZaaktypen: vi.fn().mockReturnValue(of([])) });
+    await render(CatalogusPage, { providers });
+
+    expect(await screen.findByText(/geen gepubliceerde zaaktypen/i)).toBeTruthy();
+  });
+
+  it('surfaces a load failure instead of swallowing it', async () => {
+    const { providers } = setup({
+      getBeheerCatalogiZaaktypen: vi.fn().mockReturnValue(throwError(() => new Error('403'))),
+    });
+    await render(CatalogusPage, { providers });
+
+    expect(await screen.findByText(/kon de catalogus niet laden/i)).toBeTruthy();
+  });
+
+  it('has no WCAG 2.1 AA violations', async () => {
+    document.documentElement.lang = 'nl';
+    const { container } = await render(CatalogusPage, { providers: setup().providers });
+
+    const results = await axe(container, {
+      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] },
+    });
+
+    expect(results.violations).toEqual([]);
+  });
+});

apps/beheer/src/app/catalogus/catalogus-page.ts

@@ -0,0 +1,45 @@
+import { Component, inject, signal } from '@angular/core';
+import { BeheerZaaktype, BffApiV1Service } from 'api-client';
+import { UtrechtComponentsModule } from 'ui';
+
+/**
+ * The beheer catalogus viewer (S-15a): a signed-in beheerder sees the published ZTC zaaktypen,
+ * read-only. The list is served by the BFF (`GET /beheer/catalogi/zaaktypen`), which proxies the ACL —
+ * the only code allowed to read the ZGW Catalogi API (§8.1, ADR-0025). Managing default-fill is S-15b.
+ */
+@Component({
+  selector: 'app-catalogus-page',
+  imports: [UtrechtComponentsModule],
+  templateUrl: './catalogus-page.html',
+})
+export class CatalogusPage {
+  private readonly bff = inject(BffApiV1Service);
+
+  protected readonly items = signal<BeheerZaaktype[]>([]);
+  protected readonly loading = signal(false);
+  protected readonly loaded = signal(false);
+  protected readonly failed = signal(false);
+
+  constructor() {
+    this.load();
+  }
+
+  load(): void {
+    this.loading.set(true);
+    this.failed.set(false);
+    this.bff.getBeheerCatalogiZaaktypen().subscribe({
+      next: (rows: BeheerZaaktype[]) => {
+        this.items.set(rows);
+        this.loading.set(false);
+        this.loaded.set(true);
+      },
+      // Surface the failure (e.g. 403 for a non-beheerder) instead of swallowing it.
+      error: () => {
+        this.items.set([]);
+        this.loading.set(false);
+        this.loaded.set(true);
+        this.failed.set(true);
+      },
+    });
+  }
+}

apps/beheer/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="nl">
+  <head>
+    <meta charset="utf-8" />
+    <title>Beheerportaal BIG-register</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="favicon.ico" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

apps/beheer/src/main.ts

@@ -0,0 +1,10 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+import { appConfig, type RuntimeConfig } from './app/app.config';
+
+// Load environment config before bootstrap so the OIDC authority is set per environment
+// (dev: localhost; compose: keycloak:8080) from a single build — 12-factor (S-08d).
+fetch('config.json')
+  .then((response) => response.json() as Promise<RuntimeConfig>)
+  .then((config) => bootstrapApplication(App, appConfig(config)))
+  .catch((err) => console.error(err));

apps/beheer/src/styles.css

@@ -0,0 +1,2 @@
+/* NL Design System theme — Utrecht design tokens (docs/frontend-decisions.md). */
+@import '@utrecht/design-tokens/dist/index.css';

apps/beheer/tsconfig.app.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}

apps/beheer/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "target": "es2022",
+    "moduleResolution": "bundler",
+    "emitDecoratorMetadata": false,
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

apps/beheer/tsconfig.spec.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"]
+}

apps/openbaar/Dockerfile

@@ -0,0 +1,25 @@
+# Multi-stage build for the openbaar portal (Angular → nginx).
+# Build context is the repo root (the app needs the pnpm workspace + libs). See infra/docker-compose.yml.
+FROM node:24-slim AS build
+WORKDIR /src
+RUN corepack enable && corepack prepare pnpm@11.5.2 --activate
+
+# Restore first (cached unless the manifests change).
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml nx.json tsconfig.base.json eslint.config.mjs ./
+RUN pnpm install --frozen-lockfile
+
+# Sources (only what the app + its libs need).
+COPY apps/openbaar apps/openbaar
+COPY libs libs
+RUN pnpm nx build openbaar
+
+FROM nginx:1.27-alpine AS runtime
+COPY apps/openbaar/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /src/dist/apps/openbaar/browser /usr/share/nginx/html
+# No runtime config: the openbaar register is anonymous (no OIDC authority to inject).
+# Make the reverse-proxy resolver engine-portable (Docker 127.0.0.11 vs podman aardvark); runs from
+# the nginx image's /docker-entrypoint.d before nginx starts.
+COPY apps/portal-nginx-resolver.sh /docker-entrypoint.d/40-resolver.sh
+RUN chmod +x /docker-entrypoint.d/40-resolver.sh
+
+EXPOSE 80

apps/openbaar/eslint.config.mjs

@@ -0,0 +1,34 @@
+import nx from '@nx/eslint-plugin';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+  ...nx.configs['flat/angular'],
+  ...nx.configs['flat/angular-template'],
+  ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    rules: {
+      '@angular-eslint/directive-selector': [
+        'error',
+        {
+          type: 'attribute',
+          prefix: 'app',
+          style: 'camelCase',
+        },
+      ],
+      '@angular-eslint/component-selector': [
+        'error',
+        {
+          type: 'element',
+          prefix: 'app',
+          style: 'kebab-case',
+        },
+      ],
+    },
+  },
+  {
+    files: ['**/*.html'],
+    // Override or add rules here
+    rules: {},
+  },
+];

apps/openbaar/nginx.conf

@@ -0,0 +1,23 @@
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Resolve the BFF via Docker's embedded DNS at request time (variable proxy_pass), so nginx starts
+  # even before the BFF is up and picks up restarts — instead of failing to load the config.
+  resolver 127.0.0.11 ipv6=off valid=30s;
+
+  # Same-origin API: proxy the anonymous openbaar endpoint group to the bff service. The api-client
+  # uses relative URLs, so the browser calls this origin and nginx forwards to the BFF — no CORS.
+  location /openbaar/ {
+    set $bff http://bff:8080;
+    proxy_pass $bff;
+    proxy_set_header Host $host;
+  }
+
+  # SPA fallback — Angular client-side routing.
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

apps/openbaar/project.json

@@ -0,0 +1,80 @@
+{
+  "name": "openbaar",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "prefix": "app",
+  "sourceRoot": "apps/openbaar/src",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@angular/build:application",
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "options": {
+        "outputPath": "dist/apps/openbaar",
+        "browser": "apps/openbaar/src/main.ts",
+        "tsConfig": "apps/openbaar/tsconfig.app.json",
+        "assets": [
+          {
+            "glob": "**/*",
+            "input": "apps/openbaar/public"
+          }
+        ],
+        "styles": ["apps/openbaar/src/styles.css"]
+      },
+      "configurations": {
+        "production": {
+          "budgets": [
+            {
+              "type": "initial",
+              "maximumWarning": "1mb",
+              "maximumError": "2mb"
+            },
+            {
+              "type": "anyComponentStyle",
+              "maximumWarning": "4kb",
+              "maximumError": "8kb"
+            }
+          ],
+          "outputHashing": "all"
+        },
+        "development": {
+          "optimization": false,
+          "extractLicenses": false,
+          "sourceMap": true
+        }
+      }
+    },
+    "serve": {
+      "continuous": true,
+      "executor": "@angular/build:dev-server",
+      "defaultConfiguration": "development",
+      "configurations": {
+        "production": {
+          "buildTarget": "openbaar:build:production"
+        },
+        "development": {
+          "buildTarget": "openbaar:build:development"
+        }
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "test": {
+      "executor": "@angular/build:unit-test",
+      "options": {
+        "watch": false
+      }
+    },
+    "serve-static": {
+      "continuous": true,
+      "executor": "@nx/web:file-server",
+      "options": {
+        "buildTarget": "openbaar:build",
+        "staticFilePath": "dist/apps/openbaar/browser",
+        "spa": true
+      }
+    }
+  }
+}

apps/openbaar/src/app/app.config.ts

@@ -0,0 +1,19 @@
+import { provideHttpClient } from '@angular/common/http';
+import {
+  ApplicationConfig,
+  provideBrowserGlobalErrorListeners,
+} from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { appRoutes } from './app.routes';
+
+/**
+ * The openbaar register is a public, anonymous read: no DigiD, no auth interceptor. The app is served
+ * same-origin as the BFF (nginx proxies /openbaar), so the api-client's relative calls stay same-origin.
+ */
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBrowserGlobalErrorListeners(),
+    provideRouter(appRoutes),
+    provideHttpClient(),
+  ],
+};

apps/openbaar/src/app/app.html

@@ -0,0 +1 @@
+<router-outlet></router-outlet>

apps/openbaar/src/app/app.routes.ts

@@ -0,0 +1,4 @@
+import { Route } from '@angular/router';
+import { RegisterPage } from './register/register-page';
+
+export const appRoutes: Route[] = [{ path: '', component: RegisterPage }];

apps/openbaar/src/app/app.spec.ts

@@ -0,0 +1,14 @@
+import { provideRouter } from '@angular/router';
+import { render } from '@testing-library/angular';
+import { App } from './app';
+
+describe('App', () => {
+  it('renders the router outlet shell', async () => {
+    const { container } = await render(App, {
+      providers: [provideRouter([])],
+    });
+
+    // The shell is a thin host for routed pages (the RegisterPage owns the heading).
+    expect(container.querySelector('router-outlet')).toBeTruthy();
+  });
+});

apps/openbaar/src/app/app.ts

@@ -0,0 +1,12 @@
+import { Component } from '@angular/core';
+import { RouterModule } from '@angular/router';
+
+@Component({
+  imports: [RouterModule],
+  selector: 'app-root',
+  templateUrl: './app.html',
+  styleUrl: './app.css',
+})
+export class App {
+  protected title = 'openbaar';
+}

apps/openbaar/src/app/register/register-page.html

@@ -0,0 +1,54 @@
+<main utrecht-document class="utrecht-theme">
+  <utrecht-article>
+    <utrecht-heading-1>Openbaar BIG-register</utrecht-heading-1>
+    <p utrecht-paragraph>
+      Zoek in het openbare register van BIG-registraties. Alleen publieke gegevens worden getoond.
+    </p>
+
+    <div role="search">
+      <label for="register-search" utrecht-form-label>Zoek op referentie</label>
+      <input
+        id="register-search"
+        type="search"
+        utrecht-textbox
+        [ngModel]="query()"
+        (ngModelChange)="query.set($event)"
+        [ngModelOptions]="{ standalone: true }"
+        (keyup.enter)="search()"
+      />
+      <button
+        utrecht-button
+        appearance="primary-action-button"
+        type="button"
+        [disabled]="loading()"
+        (click)="search()"
+      >
+        Zoeken
+      </button>
+    </div>
+
+    @if (loading()) {
+      <p utrecht-paragraph role="status">Bezig met laden…</p>
+    } @else if (searched() && entries().length === 0) {
+      <p utrecht-paragraph role="status">Geen inschrijvingen gevonden.</p>
+    } @else if (entries().length > 0) {
+      <table utrecht-table>
+        <caption>Inschrijvingen in het openbaar register</caption>
+        <thead>
+          <tr>
+            <th scope="col">Referentie</th>
+            <th scope="col">Status</th>
+          </tr>
+        </thead>
+        <tbody>
+          @for (entry of entries(); track entry.id) {
+            <tr>
+              <td>{{ entry.reference }}</td>
+              <td>{{ entry.status }}</td>
+            </tr>
+          }
+        </tbody>
+      </table>
+    }
+  </utrecht-article>
+</main>

apps/openbaar/src/app/register/register-page.spec.ts

@@ -0,0 +1,59 @@
+import { fireEvent, render, screen } from '@testing-library/angular';
+import { of } from 'rxjs';
+import { BffApiV1Service, type OpenbaarEntry } from 'api-client';
+import { axe } from 'vitest-axe';
+import { RegisterPage } from './register-page';
+
+const sample: OpenbaarEntry[] = [
+  { id: 'zaak-abc', status: 'INGEDIEND', reference: 'REG-abc' },
+  { id: 'zaak-def', status: 'INGESCHREVEN', reference: 'REG-def' },
+];
+
+function providers(get = vi.fn().mockReturnValue(of(sample))) {
+  return {
+    get,
+    providers: [{ provide: BffApiV1Service, useValue: { getOpenbaarRegister: get } }],
+  };
+}
+
+describe('RegisterPage', () => {
+  it('lists the public register entries from the BFF on open', async () => {
+    const { get } = providers();
+    await render(RegisterPage, { providers: providers(get).providers });
+
+    expect(get).toHaveBeenCalled();
+    // The Referentie column shows the citizen's reference (matches the submit confirmation, #78),
+    // not the internal zaak id.
+    expect(await screen.findByText(/REG-abc/)).toBeTruthy();
+    expect(screen.getByText(/INGEDIEND/)).toBeTruthy();
+    expect(screen.getByText(/REG-def/)).toBeTruthy();
+  });
+
+  it('searches by the entered term', async () => {
+    const get = vi.fn().mockReturnValue(of(sample));
+    await render(RegisterPage, { providers: providers(get).providers });
+
+    fireEvent.input(screen.getByRole('searchbox'), { target: { value: 'zaak-abc' } });
+    fireEvent.click(screen.getByRole('button', { name: /zoek/i }));
+
+    expect(get).toHaveBeenLastCalledWith({ q: 'zaak-abc' });
+  });
+
+  it('shows an empty-state message when the register has no matches', async () => {
+    const get = vi.fn().mockReturnValue(of([] as OpenbaarEntry[]));
+    await render(RegisterPage, { providers: providers(get).providers });
+
+    expect(await screen.findByText(/geen inschrijvingen gevonden/i)).toBeTruthy();
+  });
+
+  it('has no WCAG 2.1 AA violations', async () => {
+    document.documentElement.lang = 'nl';
+    const { container } = await render(RegisterPage, { providers: providers().providers });
+
+    const results = await axe(container, {
+      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'] },
+    });
+
+    expect(results.violations).toEqual([]);
+  });
+});

apps/openbaar/src/app/register/register-page.ts

@@ -0,0 +1,45 @@
+import { Component, inject, signal } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { BffApiV1Service, type OpenbaarEntry } from 'api-client';
+import { UtrechtComponentsModule } from 'ui';
+
+/**
+ * The openbaar (public) BIG-register: an anonymous search over the read projection's public-safe
+ * view (id + status only — bsn/naam never leave the BFF; ADR-0010). Loads the full register on open
+ * and filters by the search term via the BFF's `/openbaar/register?q=` endpoint (S-09).
+ */
+@Component({
+  selector: 'app-register-page',
+  imports: [FormsModule, UtrechtComponentsModule],
+  templateUrl: './register-page.html',
+})
+export class RegisterPage {
+  private readonly bff = inject(BffApiV1Service);
+
+  protected readonly query = signal('');
+  protected readonly entries = signal<OpenbaarEntry[]>([]);
+  protected readonly loading = signal(false);
+  protected readonly searched = signal(false);
+
+  constructor() {
+    // Show the full register on open; the search box narrows it.
+    this.search();
+  }
+
+  search(): void {
+    const q = this.query().trim();
+    this.loading.set(true);
+    this.bff.getOpenbaarRegister(q ? { q } : {}).subscribe({
+      next: (rows: OpenbaarEntry[]) => {
+        this.entries.set(rows);
+        this.loading.set(false);
+        this.searched.set(true);
+      },
+      error: () => {
+        this.entries.set([]);
+        this.loading.set(false);
+        this.searched.set(true);
+      },
+    });
+  }
+}

apps/openbaar/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="nl">
+  <head>
+    <meta charset="utf-8" />
+    <title>Openbaar BIG-register</title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/x-icon" href="favicon.ico" />
+  </head>
+  <body>
+    <app-root></app-root>
+  </body>
+</html>

apps/openbaar/src/main.ts

@@ -0,0 +1,6 @@
+import { bootstrapApplication } from '@angular/platform-browser';
+import { App } from './app/app';
+import { appConfig } from './app/app.config';
+
+// The openbaar register is anonymous (no DigiD, no runtime config) — bootstrap directly.
+bootstrapApplication(App, appConfig).catch((err) => console.error(err));

apps/openbaar/src/styles.css

@@ -0,0 +1,2 @@
+/* NL Design System theme — Utrecht design tokens (docs/frontend-decisions.md). */
+@import '@utrecht/design-tokens/dist/index.css';

apps/openbaar/tsconfig.app.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}

apps/openbaar/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "target": "es2022",
+    "moduleResolution": "bundler",
+    "emitDecoratorMetadata": false,
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "enableI18nLegacyMessageIdFormat": false,
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

apps/openbaar/tsconfig.spec.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"]
+}

apps/portal-nginx-resolver.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Point nginx's reverse-proxy `resolver` at THIS container's real DNS server.
+#
+# The portal nginx configs use a variable proxy_pass, which needs a `resolver` so the BFF hostname is
+# resolved at request time (nginx can start before the BFF is up). The config hardcodes Docker's
+# embedded DNS (127.0.0.11) — correct on Docker/Docker Desktop, but rootless podman uses a
+# network-specific address (aardvark, e.g. 10.89.0.1), so proxied calls 502 there. Read the actual
+# nameserver from /etc/resolv.conf and substitute it, so the reverse proxy works on any engine.
+#
+# Runs from the nginx image's /docker-entrypoint.d/ before nginx starts. On Docker the nameserver IS
+# 127.0.0.11, so the substitution is a no-op. Guarded (no `set -e`) so it's safe whether the nginx
+# entrypoint executes or sources it.
+ns="$(awk '/^nameserver/{print $2; exit}' /etc/resolv.conf 2>/dev/null)"
+if [ -n "$ns" ] && [ "$ns" != "127.0.0.11" ]; then
+  sed -i "s/resolver 127\.0\.0\.11/resolver $ns/" /etc/nginx/conf.d/default.conf 2>/dev/null || true
+  echo "portal-nginx-resolver: set resolver to $ns"
+fi

apps/self-service/Dockerfile

@@ -0,0 +1,27 @@
+# Multi-stage build for the self-service portal (Angular → nginx).
+# Build context is the repo root (the app needs the pnpm workspace + libs). See infra/docker-compose.yml.
+FROM node:24-slim AS build
+WORKDIR /src
+RUN corepack enable && corepack prepare pnpm@11.5.2 --activate
+
+# Restore first (cached unless the manifests change).
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml nx.json tsconfig.base.json eslint.config.mjs ./
+RUN pnpm install --frozen-lockfile
+
+# Sources (only what the app + its libs need).
+COPY apps/self-service apps/self-service
+COPY libs libs
+RUN pnpm nx build self-service
+
+FROM nginx:1.27-alpine AS runtime
+COPY apps/self-service/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /src/dist/apps/self-service/browser /usr/share/nginx/html
+# Compose-time OIDC config: the browser (Playwright, on the compose network) reaches Keycloak by
+# service name, so the token issuer matches the BFF's authority (host-consistent, ADR-0010).
+RUN printf '{ "authority": "http://keycloak:8080/realms/digid" }\n' > /usr/share/nginx/html/config.json
+# Make the reverse-proxy resolver engine-portable (Docker 127.0.0.11 vs podman aardvark); runs from
+# the nginx image's /docker-entrypoint.d before nginx starts.
+COPY apps/portal-nginx-resolver.sh /docker-entrypoint.d/40-resolver.sh
+RUN chmod +x /docker-entrypoint.d/40-resolver.sh
+
+EXPOSE 80

apps/self-service/nginx.conf

@@ -0,0 +1,29 @@
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Resolve the BFF via Docker's embedded DNS at request time (variable proxy_pass), so nginx starts
+  # even before the BFF is up and picks up restarts — instead of failing to load the config.
+  resolver 127.0.0.11 ipv6=off valid=30s;
+
+  # Same-origin API: proxy the BFF endpoint groups to the bff service. The api-client uses relative
+  # URLs, so the browser calls this origin and nginx forwards to the BFF — no CORS, and the DigiD
+  # token (same-origin) is attached by the app's interceptor (S-08d/ADR-0010).
+  location /self-service/ {
+    set $bff http://bff:8080;
+    proxy_pass $bff;
+    proxy_set_header Host $host;
+  }
+  location /openbaar/ {
+    set $bff http://bff:8080;
+    proxy_pass $bff;
+    proxy_set_header Host $host;
+  }
+
+  # SPA fallback — Angular client-side routing.
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

apps/self-service/public/config.json

@@ -0,0 +1,3 @@
+{
+  "authority": "http://localhost:8180/realms/digid"
+}

apps/self-service/src/app/app.config.spec.ts

@@ -0,0 +1,65 @@
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import { BffApiV1Service } from 'api-client';
+import { authInterceptor } from 'auth';
+import { AbstractSecurityStorage, ConfigurationService } from 'angular-auth-oidc-client';
+import { SECURE_API_ROUTES } from './app.config';
+
+// Guards the DigiD token wiring end-to-end. The api-client calls the BFF with RELATIVE URLs, and the
+// angular-auth-oidc-client interceptor attaches the token only when `req.url` starts with a configured
+// secureRoute. A regression to an absolute origin (as once shipped) makes the relative URL never match,
+// so the submit goes out unauthenticated and fails silently. This drives the REAL interceptor and the
+// REAL api-client against the REAL production route value (SECURE_API_ROUTES); only the config source
+// and the token storage are faked, so the assertion turns on the actual route-matching.
+describe('self-service DigiD token wiring', () => {
+  let http: HttpTestingController;
+  let bff: BffApiV1Service;
+  const token = 'digid-access-token';
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(withInterceptors([authInterceptor()])),
+        provideHttpClientTesting(),
+        {
+          provide: ConfigurationService,
+          useValue: {
+            hasAtLeastOneConfig: () => true,
+            getAllConfigurations: () => [{ configId: 'digid', secureRoutes: SECURE_API_ROUTES }],
+          },
+        },
+        {
+          // A signed-in session: the storage the interceptor's token lookup reads from.
+          provide: AbstractSecurityStorage,
+          useValue: {
+            read: () => JSON.stringify({ authzData: token, authnResult: { id_token: 'id-token' } }),
+            write: () => undefined,
+            remove: () => undefined,
+            clear: () => undefined,
+          },
+        },
+      ],
+    });
+    http = TestBed.inject(HttpTestingController);
+    bff = TestBed.inject(BffApiV1Service);
+  });
+
+  afterEach(() => http.verify());
+
+  it('attaches the bearer token to the relative self-service BFF call', () => {
+    bff.postSelfServiceRegistrations().subscribe();
+
+    const req = http.expectOne('/self-service/registrations');
+    expect(req.request.headers.get('Authorization')).toBe(`Bearer ${token}`);
+    req.flush({ registrationId: 'reg-1', status: 'Ingediend' });
+  });
+
+  it('leaves the anonymous openbaar register call unauthenticated', () => {
+    bff.getOpenbaarRegister().subscribe();
+
+    const req = http.expectOne((r) => r.url === '/openbaar/register');
+    expect(req.request.headers.has('Authorization')).toBe(false);
+    req.flush([]);
+  });
+});

apps/self-service/src/app/app.config.ts

@@ -7,16 +7,36 @@ import { provideRouter } from '@angular/router';
 import { authInterceptor, provideDigiadAuth } from 'auth';
 import { appRoutes } from './app.routes';
 
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideBrowserGlobalErrorListeners(),
-    provideRouter(appRoutes),
-    provideHttpClient(withInterceptors([authInterceptor()])),
-    // Dev defaults (host ports). The compose-served app overrides these for the stack (S-08d).
-    provideDigiadAuth({
-      authority: 'http://localhost:8180/realms/digid',
-      redirectUrl: typeof window !== 'undefined' ? window.location.origin : '/',
-      secureApiOrigin: 'http://localhost:8080',
-    }),
-  ],
-};
+/** Environment-specific settings fetched from /config.json at startup (see main.ts). */
+export interface RuntimeConfig {
+  /** The Keycloak `digid` realm issuer as the browser reaches it (dev: localhost; compose: keycloak:8080). */
+  authority: string;
+}
+
+/**
+ * Route prefixes whose requests carry the DigiD token. These MUST match the **relative** URLs the
+ * api-client actually calls (same-origin via the nginx proxy) — the interceptor matches on `req.url`,
+ * which stays relative, so an absolute origin would never match and the token would go unattached.
+ * `/openbaar/` is deliberately excluded: it is the anonymous public register.
+ */
+export const SECURE_API_ROUTES = ['/self-service/'];
+
+/**
+ * Build the app providers from runtime config. `redirectUrl` is the app's own origin (where Keycloak
+ * redirects back). `secureRoutes` uses {@link SECURE_API_ROUTES} — relative prefixes, not the origin.
+ */
+export function appConfig(runtime: RuntimeConfig): ApplicationConfig {
+  const origin = typeof window !== 'undefined' ? window.location.origin : '/';
+  return {
+    providers: [
+      provideBrowserGlobalErrorListeners(),
+      provideRouter(appRoutes),
+      provideHttpClient(withInterceptors([authInterceptor()])),
+      provideDigiadAuth({
+        authority: runtime.authority,
+        redirectUrl: origin,
+        secureRoutes: SECURE_API_ROUTES,
+      }),
+    ],
+  };
+}

apps/self-service/src/app/registration/registration-page.html

@@ -3,11 +3,63 @@
     <utrecht-heading-1>Zelfservice — BIG-registratie</utrecht-heading-1>
 
     @if (submitted()) {
-      <p utrecht-paragraph role="status">
-        Uw registratie is ontvangen. Referentie: {{ reference() }}.
-      </p>
+      @if (withdrawn()) {
+        <p utrecht-paragraph role="status">
+          Uw registratie met referentie {{ reference() }} is ingetrokken.
+        </p>
+      } @else {
+        <p utrecht-paragraph role="status">
+          Uw registratie is ontvangen. Referentie: {{ reference() }}.
+        </p>
+        @if (documentsProvided()) {
+          <p utrecht-paragraph role="status">Uw documenten zijn aangeleverd.</p>
+        } @else {
+          @if (provideDocumentsFailed()) {
+            <p utrecht-paragraph role="alert">
+              Het aanleveren van uw documenten is niet gelukt. Probeer het opnieuw.
+            </p>
+          }
+          <p utrecht-paragraph>Lever uw diploma aan (PDF).</p>
+          <label utrecht-form-label for="diploma">Diploma</label>
+          <input
+            id="diploma"
+            type="file"
+            accept="application/pdf"
+            [disabled]="providingDocuments()"
+            (change)="onFileSelected($event)"
+          />
+          <button
+            utrecht-button
+            appearance="primary-action-button"
+            type="button"
+            [disabled]="providingDocuments() || !selectedFile()"
+            (click)="provideDocuments()"
+          >
+            Documenten aanleveren
+          </button>
+        }
+        @if (withdrawFailed()) {
+          <p utrecht-paragraph role="alert">
+            Het intrekken van uw registratie is niet gelukt. Probeer het opnieuw.
+          </p>
+        }
+        <button
+          utrecht-button
+          appearance="secondary-action-button"
+          type="button"
+          [disabled]="withdrawing()"
+          (click)="withdraw()"
+        >
+          Trek aanvraag in
+        </button>
+      }
     } @else {
       <p utrecht-paragraph>U bent ingelogd met BSN {{ bsn() }}.</p>
+      @if (failed()) {
+        <p utrecht-paragraph role="alert">
+          Er ging iets mis bij het indienen van uw registratie. Probeer het opnieuw.
+        </p>
+      }
       <button
         utrecht-button
         appearance="primary-action-button"

apps/self-service/src/app/registration/registration-page.spec.ts

@@ -1,6 +1,6 @@
 import { signal } from '@angular/core';
 import { fireEvent, render, screen } from '@testing-library/angular';
-import { of } from 'rxjs';
+import { of, throwError } from 'rxjs';
 import { AuthService } from 'auth';
 import { BffApiV1Service } from 'api-client';
 import { axe } from 'vitest-axe';
@@ -17,12 +17,29 @@ class FakeAuth extends AuthService {
   }
 }
 
-function providers(post = vi.fn().mockReturnValue(of({ registrationId: 'reg-9', status: 'Ingediend' }))) {
+function providers(
+  post = vi.fn().mockReturnValue(of({ registrationId: 'reg-9', status: 'Ingediend' })),
+  withdraw = vi.fn().mockReturnValue(of(undefined)),
+  provideDocuments = vi.fn().mockReturnValue(of(undefined)),
+  // Resume lookup (S-26): default to 204/empty — no in-flight registration, so the submit form shows.
+  getCurrent = vi.fn().mockReturnValue(of(undefined)),
+) {
   return {
     post,
+    withdraw,
+    provideDocuments,
+    getCurrent,
     providers: [
       { provide: AuthService, useClass: FakeAuth },
-      { provide: BffApiV1Service, useValue: { postSelfServiceRegistrations: post } },
+      {
+        provide: BffApiV1Service,
+        useValue: {
+          getSelfServiceRegistrations: getCurrent,
+          postSelfServiceRegistrations: post,
+          postSelfServiceRegistrationsIdWithdraw: withdraw,
+          postSelfServiceRegistrationsIdDocuments: provideDocuments,
+        },
+      },
     ],
   };
 }
@@ -43,6 +60,104 @@ describe('RegistrationPage', () => {
     expect(await screen.findByText(/ontvangen/i)).toBeTruthy();
   });
 
+  it('resumes an existing registration on load, without submitting again (S-26)', async () => {
+    const { post, providers: p } = providers(
+      undefined,
+      undefined,
+      undefined,
+      vi.fn().mockReturnValue(of({ registrationId: 'reg-77', status: 'Ingediend' })),
+    );
+    await render(RegistrationPage, { providers: p });
+
+    // The confirmation view is restored from the in-flight registration — no submit click.
+    expect(await screen.findByText(/ontvangen/i)).toBeTruthy();
+    expect(screen.getByText(/reg-77/)).toBeTruthy();
+    expect(post).not.toHaveBeenCalled();
+  });
+
+  it('shows an error and keeps the submit available when the BFF call fails', async () => {
+    const { post, providers: p } = providers(vi.fn().mockReturnValue(throwError(() => new Error('BFF rejected'))));
+    await render(RegistrationPage, { providers: p });
+
+    fireEvent.click(screen.getByRole('button', { name: /indienen/i }));
+
+    expect(post).toHaveBeenCalledTimes(1);
+    // The failure is surfaced (not swallowed), the confirmation is not shown, and the user can retry.
+    expect(await screen.findByRole('alert')).toBeTruthy();
+    expect(screen.queryByText(/ontvangen/i)).toBeNull();
+    expect(screen.getByRole('button', { name: /indienen/i })).toBeTruthy();
+  });
+
+  it('offers to withdraw after submitting, and withdrawing confirms', async () => {
+    const { withdraw, providers: p } = providers();
+    await render(RegistrationPage, { providers: p });
+
+    fireEvent.click(screen.getByRole('button', { name: /indienen/i }));
+    await screen.findByText(/ontvangen/i);
+
+    fireEvent.click(await screen.findByRole('button', { name: /trek aanvraag in/i }));
+
+    // The withdrawal is keyed by the reference the submit returned, and the page confirms it.
+    expect(withdraw).toHaveBeenCalledWith('reg-9');
+    expect(await screen.findByText(/ingetrokken/i)).toBeTruthy();
+  });
+
+  // A small PDF file the citizen "uploads"; the component base64-encodes it client-side.
+  const diploma = () => new File([new Uint8Array([1, 2, 3])], 'diploma.pdf', { type: 'application/pdf' });
+
+  it('uploads a chosen diploma after submitting, and doing so confirms', async () => {
+    const { provideDocuments, providers: p } = providers();
+    await render(RegistrationPage, { providers: p });
+
+    fireEvent.click(screen.getByRole('button', { name: /indienen/i }));
+    await screen.findByText(/ontvangen/i);
+
+    // Choose the file, then upload it.
+    fireEvent.change(screen.getByLabelText(/diploma/i), { target: { files: [diploma()] } });
+    fireEvent.click(await screen.findByRole('button', { name: /documenten aanleveren/i }));
+
+    // The upload is keyed by the reference and carries the base64 file + its name; the page confirms.
+    expect(await screen.findByText(/documenten.*aangeleverd/i)).toBeTruthy();
+    expect(provideDocuments).toHaveBeenCalledWith(
+      'reg-9',
+      expect.objectContaining({ fileName: 'diploma.pdf', contentType: 'application/pdf', contentBase64: expect.any(String) }),
+    );
+  });
+
+  it('surfaces a diploma-upload failure and keeps the action available', async () => {
+    const { providers: p } = providers(
+      vi.fn().mockReturnValue(of({ registrationId: 'reg-9', status: 'Ingediend' })),
+      vi.fn().mockReturnValue(of(undefined)),
+      vi.fn().mockReturnValue(throwError(() => new Error('documents rejected'))),
+    );
+    await render(RegistrationPage, { providers: p });
+
+    fireEvent.click(screen.getByRole('button', { name: /indienen/i }));
+    await screen.findByText(/ontvangen/i);
+    fireEvent.change(screen.getByLabelText(/diploma/i), { target: { files: [diploma()] } });
+    fireEvent.click(await screen.findByRole('button', { name: /documenten aanleveren/i }));
+
+    expect(await screen.findByRole('alert')).toBeTruthy();
+    expect(screen.queryByText(/aangeleverd/i)).toBeNull();
+    expect(screen.getByRole('button', { name: /documenten aanleveren/i })).toBeTruthy();
+  });
+
+  it('surfaces a withdraw failure and keeps the action available', async () => {
+    const { providers: p } = providers(
+      vi.fn().mockReturnValue(of({ registrationId: 'reg-9', status: 'Ingediend' })),
+      vi.fn().mockReturnValue(throwError(() => new Error('withdraw rejected'))),
+    );
+    await render(RegistrationPage, { providers: p });
+
+    fireEvent.click(screen.getByRole('button', { name: /indienen/i }));
+    await screen.findByText(/ontvangen/i);
+    fireEvent.click(await screen.findByRole('button', { name: /trek aanvraag in/i }));
+
+    expect(await screen.findByRole('alert')).toBeTruthy();
+    expect(screen.queryByText(/is ingetrokken/i)).toBeNull();
+    expect(screen.getByRole('button', { name: /trek aanvraag in/i })).toBeTruthy();
+  });
+
   it('has no WCAG 2.1 AA violations on the submit page', async () => {
     // The portal is Dutch; the real index.html sets lang. Set it here so the document-level
     // html-has-lang rule reflects the app, not the bare jsdom document.

apps/self-service/src/app/registration/registration-page.ts

@@ -1,19 +1,23 @@
-import { Component, inject, signal } from '@angular/core';
-import { BffApiV1Service, type SubmitAccepted } from 'api-client';
+import { Component, inject, type OnInit, signal } from '@angular/core';
+import { BffApiV1Service, type CurrentRegistration, type SubmitAccepted } from 'api-client';
 import { AuthService } from 'auth';
 import { UtrechtComponentsModule } from 'ui';
 
 /**
  * The self-service submit page: a signed-in zorgprofessional confirms and submits their BIG
  * registration. The bsn comes from the DigiD token (not a form field), so this is a confirm-and-
- * submit flow that posts to the BFF and shows the returned reference (ADR-0010; S-08c).
+ * submit flow that posts to the BFF and shows the returned reference (ADR-0010; S-08c). After
+ * submitting they can withdraw it — "trek aanvraag in" — keyed by that reference (S-11c).
+ *
+ * On load it asks the BFF for the caller's current open registration and restores the submitted view
+ * if there is one, so a page refresh no longer strands an in-flight registration (S-26).
  */
 @Component({
   selector: 'app-registration-page',
   imports: [UtrechtComponentsModule],
   templateUrl: './registration-page.html',
 })
-export class RegistrationPage {
+export class RegistrationPage implements OnInit {
   private readonly auth = inject(AuthService);
   private readonly bff = inject(BffApiV1Service);
 
@@ -21,13 +25,116 @@ export class RegistrationPage {
   protected readonly submitting = signal(false);
   protected readonly reference = signal<string | undefined>(undefined);
   protected readonly submitted = signal(false);
+  protected readonly failed = signal(false);
+  protected readonly withdrawing = signal(false);
+  protected readonly withdrawn = signal(false);
+  protected readonly withdrawFailed = signal(false);
+  protected readonly providingDocuments = signal(false);
+  protected readonly documentsProvided = signal(false);
+  protected readonly provideDocumentsFailed = signal(false);
+  protected readonly selectedFile = signal<File | undefined>(undefined);
+
+  /** Resume an existing in-flight registration after a refresh (S-26): the BFF returns the caller's
+   * current open registration, or 204 (empty body) when there is none — in which case we show the
+   * submit form as before. Failures are non-fatal for the same reason. */
+  ngOnInit(): void {
+    this.bff.getSelfServiceRegistrations().subscribe({
+      next: (current: CurrentRegistration | void) => {
+        if (current && current.registrationId) {
+          this.reference.set(current.registrationId);
+          this.submitted.set(true);
+        }
+      },
+      error: () => {
+        // No resumable registration (or the lookup failed) — fall back to the submit form.
+      },
+    });
+  }
 
   submit(): void {
     this.submitting.set(true);
-    this.bff.postSelfServiceRegistrations().subscribe((accepted: SubmitAccepted) => {
-      this.reference.set(accepted.registrationId);
-      this.submitted.set(true);
-      this.submitting.set(false);
+    this.failed.set(false);
+    this.bff.postSelfServiceRegistrations().subscribe({
+      next: (accepted: SubmitAccepted) => {
+        this.reference.set(accepted.registrationId);
+        this.submitted.set(true);
+        this.submitting.set(false);
+      },
+      // Surface the failure instead of swallowing it: re-enable the button so the user can retry.
+      error: () => {
+        this.failed.set(true);
+        this.submitting.set(false);
+      },
+    });
+  }
+
+  onFileSelected(event: Event): void {
+    const input = event.target as HTMLInputElement;
+    this.selectedFile.set(input.files?.[0] ?? undefined);
+  }
+
+  async provideDocuments(): Promise<void> {
+    const reference = this.reference();
+    const file = this.selectedFile();
+    if (!reference || !file) {
+      return;
+    }
+    this.providingDocuments.set(true);
+    this.provideDocumentsFailed.set(false);
+    let contentBase64: string;
+    try {
+      contentBase64 = await readAsBase64(file);
+    } catch {
+      this.provideDocumentsFailed.set(true);
+      this.providingDocuments.set(false);
+      return;
+    }
+    this.bff
+      .postSelfServiceRegistrationsIdDocuments(reference, {
+        contentBase64,
+        fileName: file.name,
+        contentType: file.type || 'application/pdf',
+      })
+      .subscribe({
+        next: () => {
+          this.documentsProvided.set(true);
+          this.providingDocuments.set(false);
+        },
+        // Surface the failure instead of swallowing it: keep the action so the user can retry.
+        error: () => {
+          this.provideDocumentsFailed.set(true);
+          this.providingDocuments.set(false);
+        },
+      });
+  }
+
+  withdraw(): void {
+    const reference = this.reference();
+    if (!reference) {
+      return;
+    }
+    this.withdrawing.set(true);
+    this.withdrawFailed.set(false);
+    this.bff.postSelfServiceRegistrationsIdWithdraw(reference).subscribe({
+      next: () => {
+        this.withdrawn.set(true);
+        this.withdrawing.set(false);
+      },
+      // Surface the failure instead of swallowing it: keep the action so the user can retry.
+      error: () => {
+        this.withdrawFailed.set(true);
+        this.withdrawing.set(false);
+      },
     });
   }
 }
+
+/** Read a file's bytes as a base64 string (without the `data:...;base64,` prefix). */
+function readAsBase64(file: File): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(((reader.result as string) ?? '').split(',', 2)[1] ?? '');
+    reader.onerror = () => reject(reader.error ?? new Error('Could not read the file.'));
+    reader.readAsDataURL(file);
+  });
+}

apps/self-service/src/main.ts

@@ -1,5 +1,10 @@
 import { bootstrapApplication } from '@angular/platform-browser';
-import { appConfig } from './app/app.config';
 import { App } from './app/app';
+import { appConfig, type RuntimeConfig } from './app/app.config';
 
-bootstrapApplication(App, appConfig).catch((err) => console.error(err));
+// Load environment config before bootstrap so the OIDC authority is set per environment
+// (dev: localhost; compose: keycloak:8080) from a single build — 12-factor (S-08d).
+fetch('config.json')
+  .then((response) => response.json() as Promise<RuntimeConfig>)
+  .then((config) => bootstrapApplication(App, appConfig(config)))
+  .catch((err) => console.error(err));

docs/architecture/adr-0011-approval-status-flow.md

@@ -0,0 +1,64 @@
+# ADR-0011: Approval sets the zaak eindstatus via the ACL and projects INGESCHREVEN from the notification alone
+
+- **Status:** Accepted
+- **Date:** 2026-07-13
+- **Deciders:** Respellion engineering
+- **Relates to:** S-09b (#75); split from S-09 (#10); builds on ADR-0001 (§8 loose coupling), ADR-0003 (ACL default-fill), ADR-0007 (OZ→NRC wiring), ADR-0008 (read projection), ADR-0009 (external-task worker)
+
+## Context
+
+The walking skeleton could submit a registration (INGEDIEND) and show it in the openbaar register,
+but nothing could **approve** it. S-09b adds a behandelaar approval that must make the entry publicly
+visible as a terminal status. There is no behandel-portal yet (S-12), so approval is triggered by a
+**temporary admin endpoint** on the Domain Service.
+
+Two decisions are non-obvious (§14) and cross service boundaries:
+
+1. **Who resolves the ZGW statustype?** Approval means "set the zaak to its final status", but the
+   domain must stay ZGW-ignorant (§8.1 — only the ACL talks to ZGW) and does not know statustype URLs.
+2. **How does the projection learn the new status?** The status is set in OpenZaak, which notifies over
+   NRC; the Event Subscriber projects it. But the subscriber **may not read OpenZaak** (§8.1), and an
+   NRC `status`/`create` notification's `resourceUrl` is the *status* resource, not the zaak, and does
+   not carry the statustype.
+
+## Decision
+
+**Approval flows Domain → ACL → OpenZaak → NRC → Event Subscriber → projection, using only the
+notification's own fields on the read side.**
+
+- **Domain.** `Registration.Approve()` advances INGEDIEND → INGESCHREVEN (requires an opened zaak; a
+  repeat is a no-op). The `ApproveRegistration` use case calls the ACL to set the zaak status, then
+  advances the aggregate. A temporary `POST /registrations/{id}/approve` endpoint drives it.
+- **ACL.** A new `POST /statussen` operation takes only the zaak URL. The ACL resolves the zaaktype's
+  **eindstatus** from the catalogus (`isEindstatus`, falling back to the highest `volgnummer`) and
+  POSTs a ZGW status against the zaak. The domain never names statustypen — the ACL owns the ZGW
+  translation (§8.1, ADR-0003).
+- **Event Subscriber.** It binds the NRC `hoofdObject` (always the zaak URL) and keys the projection on
+  it, so a `zaken`/`status`/`create` notification updates the **same** row the zaak-create created,
+  flipping it to INGESCHREVEN. It takes **any** status-create as the approval — in the walking skeleton
+  the only status ever set after creation is the approval — so it never has to read OpenZaak to learn
+  the statustype. The ZGW `resource` is retained in the notification log (new column) so a rebuild
+  reproduces the right status.
+
+## Consequences
+
+- The domain↔ACL boundary stays clean: the domain hands over a zaak URL and says "approve"; ZGW
+  statustype knowledge lives only in the ACL.
+- The projection remains rebuildable without OpenZaak (§8.1, ADR-0008): the log now records the ZGW
+  resource, which is all a rebuild needs to reproject the status.
+- The openbaar register shows real lifecycle: INGEDIEND on submit, INGESCHREVEN on approval.
+- **Walking-skeleton assumption:** "any status-create ⇒ INGESCHREVEN" holds only while approval is the
+  sole post-creation status transition. When more transitions arrive (beoordeling, afwijzing — S-12+),
+  the subscriber must distinguish statustypen. The honest options then are to carry the statustype
+  omschrijving in the notification `kenmerken`, or to have the ACL resolve it and re-notify — recorded
+  here so future-me revisits this rather than assuming it generalises.
+
+## Alternatives considered
+
+- **Inject the approved statustype URL into the ACL as config** (like the zaaktype URL). Rejected:
+  couples ACL config to seed output and adds compose/run-domain-check plumbing; runtime eindstatus
+  discovery keeps the ACL self-contained for one extra ZGW GET per approval.
+- **Have the Event Subscriber GET the status/statustype from OpenZaak** to map precisely. Rejected:
+  violates §8.1 (only the ACL talks to ZGW) and makes the projection depend on OpenZaak being up.
+- **Record the derived status in the notification log** instead of the ZGW resource. Rejected: the log
+  should retain notification *facts*, not projection semantics; the mapping stays in the projector.

docs/architecture/adr-0012-citizen-reference-correlation.md

@@ -0,0 +1,104 @@
+# ADR-0012: One citizen-facing reference across self-service and the openbaar register
+
+- **Status:** Accepted
+- **Date:** 2026-07-14
+- **Deciders:** Respellion engineering
+- **Relates to:** #78 (adr-proposal); builds on ADR-0008 (read projection), ADR-0001 (loose coupling), ADR-0009 (external-task worker / zaak creation)
+
+## Context
+
+A citizen submits through the self-service portal and is shown a confirmation with a
+**reference** so they can find their registration back in the public register. But the two
+sides showed **different identifiers**:
+
+- The self-service confirmation shows the **domain `registrationId`** — a GUID minted by the
+  domain aggregate (`RegistrationId.New()`) when the registration is created, before any zaak
+  exists.
+- The openbaar register showed the **zaak id** — the UUID from the NRC `hoofdObject` URL,
+  assigned by OpenZaak when the ACL opens the zaak.
+
+These never match, so the reference on the confirmation was useless for looking the entry up.
+The two identifiers live on opposite sides of the ACL boundary and are generated by different
+systems at different times, so there is no way to reconcile them after the fact without a
+correlating value carried across the boundary.
+
+The NRC notification the Event Subscriber consumes carries only the zaak URL plus the fixed
+`kenmerken` (`bronorganisatie`, `zaaktype`, `vertrouwelijkheidaanduiding`) — **not** the
+`registrationId`, the bsn, or the `identificatie`. ADR-0008 already recorded that filling any
+such field means reading the zaak **through the ACL** (§8.1) and deferred it as a follow-up.
+This is that follow-up, scoped to the one field the citizen actually needs.
+
+## Decision
+
+**Use the domain `registrationId` as the zaak's `identificatie`, and surface that single value
+as the citizen-facing `reference` on both portals. The Event Subscriber enriches the projection
+with the reference by reading the zaak through the ACL, and stores it in the replay log so
+rebuild stays log-only.**
+
+Concretely, following the request path:
+
+1. **Domain → ACL (write).** When the OpenZaak worker opens a zaak, it passes
+   `registration.Id` to the ACL (`IAclClient.OpenZaakAsync(bsn, reference, …)`). The ACL sets
+   it as the zaak's `identificatie` on `POST /zaken`. OpenZaak's `identificatie` is unique per
+   `bronorganisatie` and ≤ 40 chars — a GUID string fits. The ACL remains the only code that
+   constructs ZGW payloads (§8.1); the domain never sees a ZGW URL.
+2. **Event Subscriber → ACL (read).** On a notification, the subscriber asks the ACL for the
+   zaak's reference via a new `POST /zaken/reference` endpoint (`{ zaakUrl } → { reference }`),
+   which reads the zaak's `identificatie` through the ACL's OpenZaak gateway. The subscriber
+   still never talks to ZGW itself (§8.1) — it depends only on the ACL, over HTTP.
+3. **Projection + replay log.** The reference is written both to the `register_projection` row
+   **and** to the `processed_notifications` replay log (a new nullable `reference` column on
+   each). Storing it in the log is what keeps ADR-0008's "**rebuild replays the log, not
+   OpenZaak**" invariant true: `POST /admin/rebuild` reproduces the reference from the log
+   without re-reading the ACL.
+4. **BFF + openbaar.** The public view (`OpenbaarProjection.PublicView`) exposes
+   `id`, `status`, and `reference` (never bsn/naam), and the openbaar search matches on either
+   `id` or `reference`. The openbaar register's "Referentie" column now renders `reference`.
+
+The end-to-end guarantee is asserted in the Playwright walking-skeleton: the reference captured
+from the submit confirmation must appear as a cell in the public register.
+
+### Why HTTP to the ACL, not the ACL as a library
+
+ADR-0008 floated "extend the ACL with a zaak-read operation, consumed as a library." We instead
+call the ACL **over HTTP**, consistent with every other cross-service hop in this system
+(portals→BFF, domain→ACL). Sharing the ACL as a library would couple the subscriber to the
+ACL's infrastructure assembly and its ZGW client configuration, defeating the anti-corruption
+boundary. The HTTP endpoint keeps the ACL the single owner of ZGW access and its config.
+
+## Consequences
+
+**Positive**
+
+- One reference, end to end: the citizen's confirmation value is exactly what the public
+  register shows and searches by.
+- §8.1 stays intact — only the ACL reads or writes ZGW; the subscriber depends on the ACL, not
+  OpenZaak.
+- Rebuild stays log-only (ADR-0008): the reference is replayed from `processed_notifications`,
+  so `/admin/rebuild` needs no ACL/ZGW access.
+- The column additions are nullable and additive; older rows without a reference are tolerated.
+
+**Negative / costs**
+
+- A new coupling: the Event Subscriber now depends on the ACL being reachable
+  (`Acl__BaseUrl`, compose `depends_on: acl`). A registration whose reference read fails will
+  need the notification redelivered (NRC already redelivers; the projection upsert is
+  idempotent).
+- One extra HTTP hop per notification (subscriber→ACL→OpenZaak) on the projection path. Bounded:
+  one small GET per zaak, off the citizen's request path.
+- `identificatie` now carries semantic meaning (it equals the `registrationId`). If OpenZaak
+  were ever configured to auto-generate `identificatie`, the correlation would break; the ACL
+  setting it explicitly is now load-bearing.
+
+## Alternatives considered
+
+- **Carry the `registrationId` in the notification** — rejected: NRC `kenmerken` are fixed and
+  the notification content is not ours to extend; it would also couple the projection to a
+  bespoke notification shape.
+- **Show the zaak id on the confirmation instead** — rejected: the zaak does not exist yet when
+  the confirmation is returned (the worker opens it asynchronously, ADR-0009), so the domain has
+  no zaak id to show at submit time.
+- **Store only on the projection row, re-read the ACL on rebuild** — rejected: it would make
+  rebuild depend on the ACL/ZGW, breaking ADR-0008's log-only rebuild invariant.
+- **Reconcile the two ids in a lookup table** — rejected: adds write-only state and a second
+  source of truth for a value that can simply be the same on both sides.

docs/architecture/adr-0013-behandel-portal-wiring.md

@@ -0,0 +1,76 @@
+# ADR-0013: Behandel-portal wiring — multi-realm BFF auth, werkbak from Flowable tasks, decision completes the task
+
+- **Status:** Accepted
+- **Date:** 2026-07-15
+- **Deciders:** Respellion engineering
+- **Relates to:** #84 (adr-proposal), S-12 (#13); builds on ADR-0010 (BFF OIDC), ADR-0011 (approval status flow), ADR-0009 (external-task worker), ADR-0008 (read projection)
+
+## Context
+
+S-12 adds the behandel-portal: a behandelaar logs in, sees a **werkbak** of registrations awaiting
+beoordeling, and decides each (goedkeuren/afwijzen). Three questions had no obvious answer and shape
+the whole slice.
+
+1. **Which realm authenticates behandelaars, and how does the BFF accept it?** Citizens use the
+   `digid` realm (ADR-0010); staff use a separate `medewerker` realm with roles (`behandelaar`,
+   `teamlead`). Keycloak realms are distinct issuers with distinct signing keys, so the BFF's single
+   `digid`-realm JWT validation rejects a medewerker token outright.
+2. **Where does the werkbak get its data?** The registrations awaiting beoordeling could come from
+   the read projection (status-filtered rows) or from the Flowable `Beoordelen` user tasks (S-12b).
+3. **How does a decision correlate to the workflow?** The process parks at the `Beoordelen` user
+   task; the decision must advance it, and also apply the domain transition (ADR-0011).
+
+## Decision
+
+**The BFF validates a second realm for behandel endpoints; the werkbak is the set of open Flowable
+`Beoordelen` tasks (read through the domain); and a decision both applies the domain transition and
+completes the Flowable task.**
+
+- **Multi-realm BFF auth.** The BFF registers a second JWT bearer scheme (`medewerker`, authority =
+  the medewerker realm) alongside the default `digid` scheme. `/behandel/*` endpoints require an
+  authorization policy bound to the `medewerker` scheme **and** the `behandelaar` role. Keycloak puts
+  realm roles in the nested `realm_access.roles` claim, which ASP.NET does not map automatically, so
+  the scheme's `OnTokenValidated` lifts those roles onto the principal as role claims. Self-service
+  keeps the `digid` scheme. Audience validation stays off (ADR-0010's deferred hardening).
+- **Werkbak = Flowable user tasks (via the domain).** The domain's `Werkbak` query reads the open
+  `Beoordelen` tasks from the Workflow Client (§8.2, `IUserTaskClient`) and enriches each with its
+  aggregate's bsn + status; `GET /behandel/werkbak` exposes it and the BFF proxies it behind the
+  behandelaar policy. The list **is** the authoritative set of claimable/decidable work items, so a
+  decision acts on a real task with no separate correlation store. The read projection stays the
+  anonymous openbaar model — we do **not** project `IN_BEHANDELING` or populate staff-only personal
+  data (both deferred in ADR-0008) just to render a staff view.
+- **Decision completes the task (S-12c-2).** A behandelaar decision applies the domain transition
+  (aggregate + ACL for approval, per ADR-0011) **and** completes the Flowable `Beoordelen` task
+  (looked up by registrationId), so the process advances. Implemented in the next sub-slice; recorded
+  here so the boundary is decided up front.
+
+Delivery is split: **S-12c-1** (this PR) = multi-realm auth + werkbak read; **S-12c-2** = the decide
+endpoint + task completion.
+
+## Consequences
+
+**Positive**
+
+- Staff and citizens are cleanly separated by realm; the `behandelaar` role gates the behandel API.
+- The werkbak reflects exactly what a behandelaar can act on; claim/decide need no extra correlation.
+- No premature projection changes — the openbaar read model stays focused and personal-data-free.
+- Only the ACL/Workflow Client talk to their peers; the BFF still fans out only to domain/projection
+  (§8.3).
+
+**Negative / costs**
+
+- The BFF now depends on two Keycloak realms being reachable (`Keycloak:MedewerkerAuthority`).
+- Rendering the werkbak fans out to Flowable (one task query) plus a store read per task — acceptable
+  for the caseload sizes here; a denormalized staff read model is an additive follow-up if needed.
+- Realm separation (distinct issuers/keys) is validated live, not in the BFF unit tests, where issuer
+  validation is off and one test key signs both realms; the tests exercise the role-based authorization.
+
+## Alternatives considered
+
+- **Werkbak from the read projection** — rejected for now: needs new plumbing to project
+  `IN_BEHANDELING` and to populate staff-only bsn/naam (deferred, ADR-0008), plus a separate way to
+  find the Flowable task at decide-time. Revisit if a high-volume denormalized staff view is needed.
+- **One JWT scheme accepting both realms (issuer validation off)** — rejected: trusting multiple
+  issuers without validation is a security regression; two schemes keep each realm's issuer/key checked.
+- **A dedicated behandel BFF/service** — rejected as premature; one BFF with per-endpoint policies is
+  enough at this size and keeps §8.3 simple.

docs/architecture/adr-0014-withdrawal-cancels-the-process.md

@@ -0,0 +1,72 @@
+# ADR-0014: Withdrawal cancels the registratie process via a BPMN message event
+
+- **Status:** Accepted
+- **Date:** 2026-07-16
+- **Deciders:** Respellion engineering
+- **Relates to:** S-11 (#12); builds on ADR-0009 (external-task worker / Workflow Client), ADR-0013
+  (behandel-portal wiring, the Beoordelen user task)
+
+## Context
+
+S-11 lets a zorgprofessional withdraw a still-open registration ("trek aanvraag in"). S-11a already
+advances the aggregate to INGETROKKEN (domain state). But the registratie process is still running in
+Flowable — parked at the `Beoordelen` user task — so without a second step the withdrawn registration
+would linger as work for a behandelaar. The withdrawal must also **cancel the running process**.
+
+Two questions shape this sub-slice.
+
+1. **How does the case get cancelled — in code, or in the BPMN model?**
+2. **How does a withdrawal correlate to the right running process instance?**
+
+## Decision
+
+**The BPMN models the cancellation as an interrupting message boundary event on the `Beoordelen`
+task; the Workflow Client correlates a `RegistratieIngetrokken` message to the task's execution.**
+
+- **Modelled in BPMN, not deleted from code.** The `Beoordelen` user task carries an interrupting
+  message boundary event (`RegistratieIngetrokken`) that routes to a dedicated "Registratie
+  ingetrokken" end event. The process's own model says *how* a withdrawal ends it — the Workflow
+  Client only delivers the message; it never reaches into Flowable to delete an instance. This keeps
+  the workflow's control flow in the workflow (§8.2) and leaves an audit trail in Flowable history
+  (the process ended via the ingetrokken path, not a raw delete).
+- **Correlated by the registration's own process instance.** The aggregate records its Flowable
+  process instance id at submit, so the `WithdrawRegistration` handler correlates directly by that
+  id — no task lookup. The Workflow Client asks Flowable for the execution **subscribed to** the
+  `RegistratieIngetrokken` message in that instance and delivers `messageEventReceived` to it.
+  Targeting the subscribed execution (not the user task's execution — a message boundary event's
+  subscription lives on its own execution) is what makes the correlation land.
+- **Best-effort, mirroring the beoordeling.** If no open `Beoordelen` task is found (the process has
+  not yet parked there — the `OpenZaakAanmaken` window — or has already ended), the withdrawal still
+  stands: the aggregate is INGETROKKEN and the werkbak filters it out regardless (S-11b). We complete
+  the domain transition first and cancel the workflow best-effort, exactly as `BeoordeelRegistratie`
+  completes its task best-effort.
+
+## Consequences
+
+**Positive**
+
+- The cancellation path is visible in `registratie.bpmn`; the Workflow Client stays the only code
+  that talks to Flowable and does not delete instances behind the model's back.
+- Reuses the existing task-query correlation — no new plumbing, no correlation store.
+- A withdrawn case leaves the werkbak (its `Beoordelen` task is cancelled), and the werkbak also
+  filters non-open registrations as a belt-and-braces for the brief window before cancellation lands.
+
+**Negative / costs**
+
+- A withdrawal raced ahead of the process reaching `Beoordelen` (during `OpenZaakAanmaken`, seconds)
+  finds no task to cancel, so that process instance runs on to `Beoordelen` and parks there with no
+  one to act on it (it is hidden from the werkbak by the status filter). Acceptable for this
+  reference at these volumes; a process-level interrupting event subprocess would close the gap and
+  is an additive follow-up if it matters.
+- The Flowable message-correlation REST shape is validated live (verify-stack), not in the
+  Workflow Client's unit tests, which stub the HTTP exchange and assert only the request shape
+  (consistent with ADR-0009).
+
+## Alternatives considered
+
+- **Delete the process instance from the Workflow Client** (`DELETE /runtime/process-instances/{id}`)
+  — rejected: it cancels the case but hides the reason from the BPMN model; the "why" lives in code,
+  not the process. The message event keeps the cancellation a first-class part of the workflow.
+- **Interrupting message event subprocess at process level** — more robust (correlates anytime,
+  closing the `OpenZaakAanmaken`-race gap), but a heavier BPMN construct; deferred as an additive
+  change if the race proves to matter.

docs/architecture/adr-0015-beoordeling-escalation.md

@@ -0,0 +1,77 @@
+# ADR-0015: Beoordeling escalation reassigns via an external-worker task
+
+- **Status:** Accepted
+- **Date:** 2026-07-17
+- **Deciders:** Respellion engineering
+- **Relates to:** S-14 (#15); proposal #98. Builds on ADR-0009 (external-task worker / Workflow
+  Client), ADR-0013 (behandel-portal wiring, the `Beoordelen` user task), ADR-0014 (the boundary-event
+  pattern on `Beoordelen`).
+
+## Context
+
+S-14 escalates a beoordeling that a behandelaar does not pick up in time: after 14 days the case must
+move to the `teamlead` role (PRD §5, flow 5). The `Beoordelen` user task already exists, claimable by
+the `behandelaar` candidate group; the teamlead role is seeded in the medewerker realm.
+
+Two forces shape this.
+
+1. **The task must stay open.** Escalation changes *who may claim* an unclaimed beoordeling, not the
+   work itself — so the timer must be **non-interrupting**: the `Beoordelen` task keeps running while
+   escalation happens alongside it.
+2. **Reassigning an open task's candidate group needs code.** Flowable cannot rewrite the candidate
+   groups of an already-open user task from BPMN XML alone — that requires either a Java delegate/listener
+   embedded in the engine, or an out-of-process actor driving the REST API. The repository has held a
+   "stock Flowable image, no custom jars; the Workflow Client is the only code that talks to Flowable
+   (§8.2)" posture since ADR-0009.
+
+## Decision
+
+**A non-interrupting `P14D` boundary timer on `Beoordelen` fires an external-worker task
+(`BeoordelingEscaleren`); the Workflow Client reassigns the still-open `Beoordelen` task from the
+behandelaar group to teamlead.**
+
+- **Modelled in BPMN, driven by an external worker.** The timer routes a parallel token to an
+  `external-worker` service task on the `BeoordelingEscaleren` topic, ending at a dedicated "Beoordeling
+  geëscaleerd" end event. The model owns *when* escalation happens; the Workflow Client — the only code
+  that talks to Flowable (§8.2) — owns *how* the reassignment is applied, exactly as `OpenZaakAanmaken`
+  delegates the ZGW call (ADR-0009). No custom code runs inside Flowable.
+- **Reassignment is a candidate-group swap.** The escalation worker finds the still-open `Beoordelen`
+  task in the escalating instance (task query by `processInstanceId` + `taskDefinitionKey`), adds
+  `teamlead` as a candidate group via the task identity links, then removes `behandelaar`. The task now
+  belongs to the teamlead; its history and variables are untouched.
+- **Best-effort, mirroring beoordeling and withdrawal.** If the task is no longer open — the behandelaar
+  completed it in the window before the timer fired — the reassignment is a no-op. A failed reassignment
+  leaves the escalation job un-completed so Flowable redelivers it (§8.6), consistent with the
+  `OpenZaakAanmaken` worker.
+- **Segregated interface.** The escalation methods live on `IBeoordelingEscalatieClient`, separate from
+  the `OpenZaakAanmaken` worker's `IExternalWorkerClient`, so the OpenZaak worker never sees escalation
+  (interface segregation). Both are implemented by the one `FlowableWorkflowClient`.
+
+## Consequences
+
+**Positive**
+
+- The escalation trigger is visible in `registratie.bpmn`; Flowable stays a stock image, and the
+  Workflow Client remains the sole Flowable client (§8.2 upheld, not bent).
+- Reuses the external-worker mechanics (topic acquire/complete, hosted pump, per-tick scope,
+  redelivery-on-failure) wholesale — the new code is one client capability, one processor, one pump.
+- Escalation latency is bounded by the worker's poll interval (seconds) — negligible against a 14-day
+  timer.
+
+**Negative / costs**
+
+- Escalation is two REST hops (add teamlead, remove behandelaar) rather than one atomic update; between
+  them the task is briefly claimable by both groups. Harmless at these volumes, and the pair is idempotent
+  on redelivery.
+- The Flowable identity-link and management-job REST shapes are validated live (verify-domain fires the
+  timer early via the management API), not in the Workflow Client's unit tests, which stub the HTTP
+  exchange and assert only the request shape — consistent with ADR-0009 and ADR-0014.
+
+## Alternatives considered
+
+- **Flowable timer/task listener (Java delegate).** Reassign in-engine when the timer fires. Rejected:
+  it needs a custom jar in Flowable, breaking the stock-image, REST-only posture and adding a build/deploy
+  surface to the engine for no capability the external-worker route lacks.
+- **Interrupting timer that re-creates the task for teamlead.** Cancel `Beoordelen` and start a fresh
+  teamlead task. Rejected: it loses the task's identity/history and complicates correlation, where a
+  candidate-group swap on the same task expresses "the same work, now the teamlead's" directly.

docs/architecture/adr-0016-diploma-eligibility-dmn.md

@@ -0,0 +1,77 @@
+# ADR-0016: Diploma eligibility is a DMN evaluated inline as a BPMN DMN service task
+
+- **Status:** Accepted
+- **Date:** 2026-07-17
+- **Deciders:** Respellion engineering
+- **Relates to:** S-13 (#14); proposal #100. Builds on ADR-0009 (external-task worker / Workflow
+  Client), ADR-0014/0015 (the boundary-event and routing constructs on the registratie process).
+
+## Context
+
+S-13 adds flow 4: a foreign diploma must get an extra CBGV-advies assessment before beoordeling
+(PRD §5). The eligibility decision — domestic goes straight to beoordeling, foreign routes through
+CBGV-advies — needs a home. The Flowable REST app bundles a DMN engine, and the same
+`repository/deployments` machinery that deploys `registratie.bpmn` can deploy a `.dmn`. §8.2 makes
+the Workflow Client the only code that talks to Flowable; the PRD frames the workflow as "BPMN + DMN
+governing the registration workflow" (Flowable as a peer orchestration module).
+
+The issue's wording ("a DMN decision table evaluated by the Domain Service via Workflow Client")
+suggests the domain reaches into Flowable's DMN API to evaluate the decision and feeds the result
+back. That is one option; it is not the only one, and it is not the cleanest.
+
+## Decision
+
+**The diploma-eligibility DMN is deployed to Flowable and evaluated inline by the registratie process
+as a DMN service task (`flowable:type="dmn"`); an exclusive gateway routes on its output. The domain's
+only new job is to carry the diploma origin and pass it into the process as a start variable.**
+
+- **The decision lives in the workflow.** `workflows/diploma-eligibility.dmn` maps `diplomaOrigin`
+  → `route` (`Buitenlands` ⇒ `CBGV_ADVIES`, otherwise `DIRECT`). A DMN service task
+  (`flowable:type="dmn"`, `decisionTableReferenceKey=diploma-eligibility`) runs it between
+  `OpenZaakAanmaken` and `Beoordelen`, and an exclusive gateway sends `CBGV_ADVIES` through a new
+  `CBGVAdvies` user task before `Beoordelen`, `DIRECT` straight there. (A `businessRuleTask` would
+  bind Flowable's legacy Drools/KIE implementation, which `flowable-rest` does not bundle — its parse
+  handler throws `NoClassDefFoundError` at deploy time; the DMN service task is the supported route.)
+- **The domain carries the input, not the decision.** The `Registration` aggregate gains a
+  `DiplomaOrigin` (Binnenlands/Buitenlands); `SubmitRegistration` passes it to
+  `StartRegistrationProcessAsync`, which sets it as the `diplomaOrigin` start variable. The domain
+  never evaluates the DMN and never learns the route — that is the process's concern.
+- **Deployed as its own DMN-engine deployment, separate from the BPMN.** The DMN is version-controlled
+  in `workflows/` and `flowable-init` deploys it to the DMN engine via the `dmn-api`
+  (`/dmn-api/dmn-repository/deployments`), while `registratie.bpmn` goes to the process engine via
+  `/service/repository/deployments`. Two things were learned the hard way here (both cost a CI cycle):
+  (1) `flowable-rest` does **not** cascade a `.dmn` bundled inside a process `.bar` into the DMN engine
+  — the resource is stored but no decision is created, so the service task fails at runtime with
+  `FlowableObjectNotFoundException: No decision found for key`; the DMN must go through `dmn-api`.
+  (2) Flowable's DMN XML converter rejects an XML comment placed between the `<?xml?>` declaration and
+  the root `<definitions>` element (`XMLStreamReader not in START_DOCUMENT or START_ELEMENT state`),
+  unlike its BPMN converter — so the DMN's documentation comment lives *inside* `<definitions>`.
+  With the decision present in the DMN repository, the process's DMN service task resolves it across
+  deployments by key (verified live), so no shared parent deployment id is needed.
+
+## Consequences
+
+**Positive**
+
+- The eligibility rule is a first-class, inspectable workflow artefact (matching the PRD's BPMN+DMN
+  framing); business users can read/adjust the decision table without touching domain code.
+- §8.2 stays clean: the Workflow Client remains the only code talking to Flowable, and the decision
+  runs inside the process the client already started — no domain→Flowable round-trip for a decision.
+- The domain change is minimal and additive: one value on the aggregate, one start variable.
+
+**Negative / costs**
+
+- Deviates from #14's literal "evaluated by the Domain Service via Workflow Client" wording (noted on
+  the issue). The outcome — DMN decides eligibility, foreign diplomas get the CBGV step — is unchanged.
+- The DMN and its service-task wiring are validated live (verify-domain drives a foreign
+  registration through CBGV-advies and a domestic one straight to beoordeling, exercising both
+  branches), not in unit tests — consistent with ADR-0009/0014/0015. The domain unit/acceptance tests
+  cover only that the origin is carried into the process.
+
+## Alternatives considered
+
+- **Domain evaluates the DMN via the Workflow Client** (the issue's wording). Rejected: it couples
+  the domain to Flowable for a decision and splits the routing across two places (domain computes,
+  BPMN branches), for no benefit over letting the engine that owns the process own the decision.
+- **Eligibility rules in domain C#.** Rejected: it moves a governable business decision out of the
+  DMN the PRD calls for, and hard-codes what the reference app is meant to demonstrate as data.

docs/architecture/adr-0017-document-wait-timeout-cancellation.md

@@ -0,0 +1,90 @@
+# ADR-0017: A document-wait task with a 30-day interrupting timer cancels the registration
+
+- **Status:** Accepted
+- **Date:** 2026-07-20
+- **Deciders:** Respellion engineering
+- **Relates to:** S-10a (#102); proposal #104; split from S-10 (#11). Builds on ADR-0009 (external-task
+  worker / Workflow Client), ADR-0014 (withdrawal cancels the process), ADR-0015 (beoordeling
+  escalation — the boundary-timer + external-worker pattern), ADR-0016 (diploma-eligibility DMN).
+
+## Context
+
+Flow 2 (PRD §5) requires the citizen to supply documents (their diploma) after submitting. The
+registratie process must park waiting for those documents and, if they do not arrive within 30 days,
+cancel the case. S-10 was split (§13): **S-10a** is this workflow/timeout spine (backend only);
+**S-10b** wires the actual upload (portal → BFF → domain → ACL → Documenten API) that completes the
+wait. This ADR records the spine: where the wait sits, how the timeout cancels, and how the domain
+aggregate stays in sync.
+
+## Decision
+
+**A `WachtOpDocumenten` user task is inserted immediately after `OpenZaakAanmaken`, carrying an
+`cancelActivity="true"` (interrupting) `P30D` boundary timer. "Documents received" completes the task
+and the process continues into the diploma-eligibility routing; on timeout the timer cancels the task,
+runs a `RegistratieVerlopen` external-worker task, and ends the process at `endVerlopen`. A domain
+worker expires the correlated aggregate to a new terminal status `Verlopen`.**
+
+- **Where the wait sits.** Right after the zaak is opened, before the diploma-eligibility DMN: the zaak
+  exists, then the process waits for documents; on receipt it continues to the DMN routing → Beoordelen
+  (ADR-0016). The wait gates the whole assessment, so it precedes the routing rather than sitting
+  between the gateway and Beoordelen.
+- **Interrupting timer, mirroring the existing constructs.** Unlike the S-14 escalation timer
+  (non-interrupting — the Beoordelen task stays open), this timer is interrupting: when it fires the
+  wait token is consumed and the case is cancelled, like the S-11 withdrawal boundary (ADR-0014). The
+  timeout branch runs a `RegistratieVerlopen` external-worker task (topic mirrors
+  `OpenZaakAanmaken`/`BeoordelingEscaleren`) → `endVerlopen`.
+- **The domain stays authoritative.** The `RegistratieVerlopen` job carries the `registrationId`; the
+  `RegistratieVerlopenProcessor` drains it and the `ExpireRegistrationWorker` loads the aggregate and
+  calls `Registration.Expire()`, moving it to the new terminal status `Verlopen`. This keeps the
+  aggregate — which the projection/openbaar view reads — the source of truth, exactly as escalation and
+  withdrawal do. Idempotent per §8.6: a redelivered job whose aggregate is already `Verlopen` completes
+  without persisting again; an unknown registration throws so the job is redelivered.
+- **Documents-in-time transition.** `IWorkflowClient.CompleteDocumentWaitAsync(processInstanceId)`
+  completes the `WachtOpDocumenten` task (the Workflow Client remains the only code that talks to
+  Flowable, §8.2). It is best-effort — a no-op if the instance already left the wait (continued, or
+  timed out). The trigger is wired end-to-end in S-10a: a `ProvideDocuments` application use case behind
+  an owner-scoped domain endpoint `POST /registrations/{id}/documents`, a BFF passthrough
+  `POST /self-service/registrations/{id}/documents` (bsn from the DigiD token), and a "Documenten
+  aanleveren" action on the self-service page — so the walking-skeleton e2e stays green (a registration
+  can still reach the behandelaar). **S-10b replaces the stub trigger with a real file upload stored in
+  the ZGW Documenten (DRC) API via the ACL**; the completion of the wait is unchanged.
+  - *Why the trigger lives here, not in S-10b:* inserting the `WachtOpDocumenten` gate without any way
+    to pass it breaks the submit→beoordeling e2e (a merge gate). Splitting "gate" from "means to pass
+    the gate" across slices would leave `main` red, so S-10a owns both; S-10b is purely the ZGW storage
+    behind the same action.
+
+## Consequences
+
+**Positive**
+
+- The wait/timeout is a first-class workflow construct that reuses the boundary-timer + external-worker
+  pattern already proven by S-14, so the domain change is small and additive: one terminal status, one
+  worker trio (worker + processor + pump), one Workflow Client method.
+- §8 stays clean: the Workflow Client is still the only Flowable caller, and no new ZGW boundary is
+  introduced in S-10a.
+- The timeout is verified live (verify-domain fires the P30D timer via the management-API "move" idiom
+  and asserts the domain reaches `Verlopen`), consistent with ADR-0009/0014/0015.
+
+**Negative / costs**
+
+- Every registration now parks at `WachtOpDocumenten` before Beoordelen, so the other flows must supply
+  documents first: the live-check blocks (S-11/S-12b/S-13/S-14) complete the task via Flowable, and the
+  registration e2e clicks "Documenten aanleveren". A small, explicit step, but it touches every path
+  through the process.
+- On expiry S-10a cancels the *process* and marks the aggregate `Verlopen` but does **not** set the ZGW
+  *zaak* to a cancellation status — that needs a new ACL method + statustype seeding, which overlaps
+  S-10b's ACL/infra work. Deferred to S-10b (or a follow-up); noted here as the S-10a/S-10b boundary.
+- Withdrawing while parked at `WachtOpDocumenten` marks the aggregate `Ingetrokken` but does not cancel
+  the process (the withdrawal message boundary is on `Beoordelen`); the timeout worker tolerates this
+  by no-op'ing on an already-resolved aggregate. Extending withdrawal to the wait state is a follow-up.
+
+## Alternatives considered
+
+- **Pure-BPMN cancellation (timer → end event, no worker).** Rejected: the domain aggregate would then
+  be out of sync with the cancelled process, and the openbaar/projection view reads the aggregate's
+  status — the case would still look open.
+- **Wait task between the gateway and Beoordelen.** Rejected: documents gate the whole assessment
+  (including the CBGV-advies routing), so the wait belongs before the DMN, not after it.
+- **A dedicated timeout status per branch vs. reusing an open-state guard.** `Expire()` reuses the same
+  `RequireOpenForDecision` guard as withdrawal/decision, so only an `INGEDIEND`/`IN_BEHANDELING`
+  registration can lapse and the terminal states stay mutually exclusive — no new guard logic.

docs/architecture/adr-0018-diploma-upload-via-acl-documenten.md

@@ -0,0 +1,74 @@
+# ADR-0018: Diploma upload is stored in the ZGW Documenten API, fronted by the ACL
+
+- **Status:** Accepted
+- **Date:** 2026-07-20
+- **Deciders:** Respellion engineering
+- **Relates to:** S-10b (#103); proposal #107. Builds on ADR-0001 (ACL is the only ZGW caller),
+  ADR-0003 (ACL default-fill), ADR-0017 (document-wait + provision trigger). Carves the zaak-close on
+  expiry to #106 (S-10c).
+
+## Context
+
+S-10a wired the "documenten aanleveren" trigger (portal → BFF → domain → complete the WachtOpDocumenten
+wait) with the file itself stubbed. S-10b makes the upload real: the diploma must be **stored in the
+ZGW Documenten (DRC) API** and related to the zaak. §8.1 makes the ACL the only code that talks to ZGW.
+The DRC API is served by the same OpenZaak container as the Zaken/Catalogi APIs.
+
+## Decision
+
+**The ACL fronts the Documenten API: it creates an `enkelvoudiginformatieobject` and relates it to the
+zaak. The file travels base64-encoded in JSON across every hop (the portal encodes it client-side); a
+"Diploma" `informatieobjecttype` is seeded in the catalogus and injected into the ACL like the
+zaaktype.**
+
+- **ACL gateway.** `OpenZaakGateway.StoreDocumentAsync` POSTs the `enkelvoudiginformatieobject`
+  (`/documenten/api/v1/enkelvoudiginformatieobjecten`, base64 `inhoud`, `bestandsomvang`,
+  `status=definitief`) then relates it to the zaak (`/zaken/api/v1/zaakinformatieobjecten`), reusing the
+  established gateway patterns (ZGW Bearer JWT, buffered non-chunked body for uwsgi, **no CRS headers** —
+  the Documenten API is not geo, unlike zaak-create). `AclService.StoreDiplomaAsync` default-fills the
+  ZGW-mandatory fields (informatieobjecttype, bronorganisatie, vertrouwelijkheidaanduiding, `taal=nld`,
+  creatiedatum); the domain hands over only the zaak, the bytes, and the file's name/type. No new ZGW
+  scopes were needed — the seed applicatie holds `heeft_alle_autorisaties`.
+- **The file travels as base64 JSON end-to-end.** The portal reads the chosen file client-side
+  (`FileReader`) and posts `{ contentBase64, fileName, contentType }` as JSON to the BFF; the BFF
+  forwards it to the domain, and the domain to the ACL, all as JSON. This deviates from proposal #107's
+  "multipart on the portal→BFF hop": base64 JSON keeps **one** contract shape across all four services
+  (no `IFormFile`/antiforgery plumbing, no multipart in the generated client), and a diploma is a small
+  placeholder PDF, so the ~33% base64 overhead is immaterial. The ACL turns the base64 back into the
+  ZGW `inhoud`.
+- **Storing precedes completing the wait.** `ProvideDocuments` (from S-10a) now stores the diploma via
+  the ACL — once the zaak is opened — and then completes the `WachtOpDocumenten` task, so a registration
+  reaches beoordeling only after its diploma is stored. Both steps stay best-effort about missing
+  preconditions (no zaak yet → skip storage; no process yet → skip completion), mirroring withdrawal.
+- **Catalogus.** `seed_catalogus.py` (OZ_PUBLISH) creates a "Diploma" `informatieobjecttype`, relates it
+  to the zaaktype (`zaaktype-informatieobjecttypen`, while both concept), publishes both, and prints
+  `INFORMATIEOBJECTTYPE_URL`; verify-domain injects it as `Acl__Defaults__InformatieobjecttypeUrl`
+  (a zeros-uuid placeholder otherwise, so the ACL still boots).
+
+## Consequences
+
+**Positive**
+
+- §8.1 stays intact: the ACL is still the only ZGW caller; the portal only talks to the BFF; the domain
+  only crosses the ACL boundary. Adding a document was almost entirely additive (one gateway method, one
+  default, one seed block).
+- One JSON contract shape across portal/BFF/domain/ACL keeps the generated client and the service
+  contracts uniform; the upload is exercised live (ACL integration test against real OpenZaak; the
+  Playwright journey uploads a real PDF).
+
+**Negative / costs**
+
+- Base64 inflates the payload ~33% and holds the whole file in memory at each hop — fine for a small
+  diploma, but not a pattern to reuse for large documents without streaming/multipart.
+- The zaak is **not** set to a cancellation status when the 30-day term lapses — carved to #106 (S-10c),
+  which adds the cancellation statustype/resultaattype + ACL method + expiry-worker wiring.
+- Providing documents before the zaak is opened silently skips storage (best-effort); the e2e/live flow
+  avoids this by uploading only after the openbaar register shows the zaak (INGEDIEND).
+
+## Alternatives considered
+
+- **Multipart on the portal→BFF hop** (proposal #107). Rejected: it splits the transport into two shapes
+  (multipart then JSON), needs `IFormFile` + antiforgery handling and a multipart method in the generated
+  client, for no benefit at diploma size.
+- **The domain talks to the Documenten API directly.** Rejected outright: violates §8.1 (only the ACL
+  talks to ZGW).

docs/architecture/adr-0019-zaak-cancellation-on-timeout.md

@@ -0,0 +1,81 @@
+# ADR-0019: A timed-out zaak is cancelled with a distinct status + resultaat, resolved by name
+
+- **Status:** Accepted
+- **Date:** 2026-07-21
+- **Deciders:** Respellion engineering
+- **Relates to:** S-10c (#106). Completes the S-10a/S-10b boundary noted in ADR-0017 (§Consequences) and
+  reuses the ACL close-zaak machinery from S-09b (approval) and the Documenten work in ADR-0018.
+
+## Context
+
+ADR-0017 (S-10a) cancels the *process* and marks the domain aggregate `Verlopen` when the 30-day
+document term lapses, but explicitly deferred setting the ZGW **zaak** to a cancellation status. Left
+open, a timed-out zaak stays open in OpenZaak while the register shows the registration as lapsed — the
+two diverge. S-10c closes that gap: on expiry the domain must also cancel the zaak through the ACL
+(§8.1, the only code that talks to ZGW).
+
+The non-obvious part is *how to represent "cancelled" in ZGW* alongside the existing "approved" close.
+The approval path (S-09b) sets the zaak's **eindstatus** (the terminal statustype) plus a resultaat. In
+ZGW a zaaktype has exactly one eindstatus — the highest-`volgnummer` statustype — and setting it is what
+closes the zaak (`einddatum`). A second *terminal* status would collide with that single-eindstatus rule.
+
+## Decision
+
+**Model cancellation as a distinct, non-terminal `Geannuleerd` statustype plus a distinct `Vervallen`
+resultaat, and resolve both the approval and cancellation statustype/resultaat by their omschrijving
+(name) rather than by position or the eindstatus flag alone.**
+
+- **Seed.** `Geannuleerd` is seeded at `volgnummer` 2 — between `Ontvangen` (1) and the `Afgehandeld`
+  eindstatus (3) — so it is a *non-terminal* status and never displaces the eindstatus the approval path
+  resolves. A second resultaattype `Vervallen` (archiefnominatie `vernietigen`) is seeded beside the
+  approval `Geregistreerd` (`blijvend_bewaren`); both draw their `selectielijstklasse` from the
+  zaaktype's single `selectielijstProcestype` so they validate on publish.
+- **The ACL owns the mapping.** `OpenZaakGateway.SetZaakToCancellationStatusAsync` resolves `Geannuleerd`
+  + `Vervallen` by omschrijving and POSTs the resultaat then the status (OpenZaak requires a resultaat
+  before a closing/terminal status), mirroring `SetZaakToEindstatusAsync`. Exposed as
+  `AclService.CancelZaakAsync` behind the ACL endpoint `POST /annuleringen`. The omschrijvingen live as
+  constants in the gateway — the ACL, not the domain, knows which ZGW status means what (§8.1).
+- **Approval now resolves its resultaat by name too.** With two resultaattypen present, taking the first
+  is ambiguous (the Zaken API does not guarantee order), so the approval path resolves `Geregistreerd`
+  by omschrijving. Its statustype resolution is unchanged (still the eindstatus).
+- **Domain wiring.** The `ExpireRegistrationWorker` calls `IAclClient.CancelZaakAsync(zaakUrl)` **before**
+  advancing the aggregate to `Verlopen` (ACL-first, mirroring approval): if the ACL call fails the job is
+  redelivered (§8.6) rather than leaving the aggregate `Verlopen` with an open zaak. The existing
+  open-state guard stops a redelivered job from cancelling twice (a second resultaat would be a 400); a
+  registration that lapsed before its zaak was opened has nothing to cancel.
+
+## Consequences
+
+**Positive**
+
+- The domain aggregate and the ZGW zaak no longer diverge on timeout — both reflect the cancellation.
+- Reuses the approval close machinery (resultaat-then-status, ACL endpoint shape, ACL-first ordering), so
+  the change is additive and §8 stays clean (only the ACL talks to ZGW).
+- Verified at two levels: an ACL↔OpenZaak integration test asserts the live zaak reaches `Geannuleerd`
+  with a resultaat, and the domain verify script fires the real P30D timer and confirms the zaak is
+  cancelled end-to-end.
+
+**Negative / costs**
+
+- `Geannuleerd` is non-terminal, so the cancelled zaak's `einddatum` is not set — it carries a
+  cancellation status + resultaat but is not formally "closed" in ZGW. Accepted: the register reads the
+  domain aggregate's status, and a single eindstatus per zaaktype is a ZGW constraint we chose not to
+  fight. Formally closing a cancelled zaak (a second eindstatus, or reusing `Afgehandeld` with a
+  `Vervallen` resultaat) is a possible follow-up.
+- The ACL couples to the seeded omschrijvingen (`Geregistreerd`/`Geannuleerd`/`Vervallen`) by string
+  constants. This mirrors the existing implicit coupling to the catalogus (zaaktype URL, eindstatus) and
+  is documented in the gateway.
+- Renumbering `Afgehandeld` from `volgnummer` 2 to 3 means a *stale* local catalogus must have its
+  OpenZaak volumes reset for the change to take effect; CI reseeds a fresh catalogus each run.
+
+## Alternatives considered
+
+- **Shared eindstatus, distinct resultaat only** (reuse `Afgehandeld`, distinguish approval vs
+  cancellation purely by the resultaat). ZGW-idiomatic and would set `einddatum` on cancellation too, but
+  the register would show no visibly distinct cancellation *status*. Rejected in favour of the issue's
+  explicit "distinct statustype + resultaattype" outcome, which makes the cancellation legible in ZGW.
+- **A second terminal (eindstatus) `Geannuleerd`.** Rejected: ZGW allows only one eindstatus per
+  zaaktype (highest volgnummer); a second terminal status would either not close the zaak or collide with
+  the approval eindstatus resolution.
+- **Passing the target omschrijvingen from the domain.** Rejected: which ZGW status means "cancelled" is
+  ZGW vocabulary the ACL owns (§8.1); the domain says only "cancel this zaak".

docs/architecture/adr-0020-local-stack-self-seeds.md

@@ -0,0 +1,92 @@
+# ADR-0020: The local stack self-seeds the zaaktype, DMN, and NRC abonnement at bring-up
+
+- **Status:** Accepted
+- **Date:** 2026-07-22
+- **Deciders:** Respellion engineering
+- **Relates to:** S-B04 (#110). Local-stack twin of the seeding the verify-* scripts do for CI
+  (`infra/run-domain-check.sh`, `infra/verify-notification-driver.py`). Superseded in part by S-27
+  (#113), which would let the ACL resolve its zaaktype by identificatie and remove the URL injection.
+
+## Context
+
+`infra/docker-compose.local.yml` is the host-browser-friendly stack (`make local`) — the one a
+developer clicks through the portals with. It had drifted behind three slices, so a fresh bring-up
+could not complete the flow:
+
+1. The ACL pointed at a placeholder zaaktype (`…/00000000-…`), so zaak creation failed with OpenZaak
+   `400` and the registratie process stuck at `OpenZaakAanmaken` (S-05).
+2. `flowable-init` deployed only `registratie.bpmn`, not `diploma-eligibility.dmn`, so completing
+   `WachtOpDocumenten` 404'd on the missing decision and never reached `Beoordelen` (S-10a/S-13).
+3. No NRC abonnement was registered, so notifications reached NRC and went nowhere — the projection
+   and the openbaar register stayed empty (S-06).
+
+The CI stack (`infra/docker-compose.yml`) does not hit this because its `verify-*` scripts seed the
+zaaktype, deploy the DMN, and register the abonnement at *test* time. The local stack has no such
+harness — a developer just runs `make local` and browses. The non-obvious wrinkle is (1): the
+zaaktype **UUID is assigned by OpenZaak at creation**, so the ACL's zaaktype URL is not knowable when
+the compose file is written and cannot be a static value.
+
+## Decision
+
+**Make the local stack self-seed at bring-up via one-shot init containers, and hand the ACL its
+server-assigned zaaktype URL through a shared-volume env file it sources on startup.**
+
+- **DMN (gap 2).** `flowable-init` now deploys `diploma-eligibility.dmn` to the DMN engine
+  (`/flowable-rest/dmn-api/dmn-repository/deployments`) as a separate deployment alongside the BPMN —
+  identical to the CI `flowable-init`. Idempotent.
+- **Zaaktype + ACL wiring (gap 1).** A `local-seed` one-shot runs the existing
+  `infra/openzaak/seed_catalogus.py` (`OZ_PUBLISH=1`) against OpenZaak and writes the resulting
+  `Acl__Defaults__ZaaktypeUrl` / `…InformatieobjecttypeUrl` / `Acl__OpenZaak__BaseUrl` into
+  `seed-env:/out/acl.env`. The ACL mounts that volume read-only and overrides its entrypoint to
+  `sh -c 'set -a; . /seed/acl.env; set +a; exec dotnet Acl.Api.dll'`, so the real values override the
+  compose placeholders before the app reads config. The ACL `depends_on: local-seed
+  (service_completed_successfully)`.
+- **Abonnement (gap 3).** A `nrc-subscribe` one-shot registers an abonnement on the `zaken` kanaal
+  pointing at the event-subscriber's `/notifications` callback (`infra/local/register-abonnement.py`).
+  It is a leaf — nothing depends on it — so it can wait for the event-subscriber without forming a
+  cycle with the ACL bootstrap.
+- **Reach OpenZaak/NRC by container IP, not service name.** Both the seed's ZTC calls and the
+  abonnement's `callbackUrl` are validated by Django's URLValidator, which rejects a single-label host
+  like `openzaak` / `event-subscriber`. The scripts resolve the target's container IP at runtime (as
+  `infra/run-domain-check.sh` does), keeping the seeded URLs valid **and** host-consistent — the ACL's
+  base URL is set to the same OpenZaak IP that owns the zaaktype URL.
+- **Acceptance.** `make verify-local` (`infra/run-local-flow-check.sh`) submits against a fresh stack
+  and asserts the zaak opens, the case reaches the werkbak after documents, and the reference appears
+  in the openbaar register — the red-to-green test for all three gaps.
+
+## Consequences
+
+**Positive**
+
+- A fresh `make local` completes the full demo (submit → werkbak → openbaar) with no manual seeding —
+  the slice's stated outcome.
+- Reuses the proven CI mechanisms (`seed_catalogus.py`, the DMN deploy, the abonnement driver) rather
+  than inventing new ones; the only genuinely new piece is the entrypoint-sourced env file.
+- No service code changes — the fix is entirely in `infra/` (compose + two small scripts), so the ACL
+  image and the CI stack are untouched.
+
+**Negative / costs**
+
+- The two compose files diverge further: the CI stack seeds at test time, the local stack at bring-up.
+  Mitigated by reusing the same underlying scripts and cross-referencing them.
+- The ACL entrypoint override couples the local ACL to the seed-written file path (`/seed/acl.env`);
+  if the seed fails, the ACL fails to start (loud, healthcheck-visible — preferred over silently
+  running with a placeholder).
+- Container-IP-based URLs are re-derived on each bring-up; a keep-volumes restart with a changed
+  OpenZaak IP relies on OpenZaak rebuilding hyperlinked URLs from the request host (it does) so the
+  idempotent re-seed reports current-IP URLs.
+
+## Alternatives considered
+
+- **ACL resolves its zaaktype by identificatie (`BIG-REGISTRATIE`) at startup.** The cleaner,
+  less-brittle design — no server-assigned URL to capture — and it would help the CI stack too. But it
+  changes a service's runtime behaviour and its config contract, needs new ACL tests + mutation
+  coverage, and still needs a seed step to *create* the zaaktype. Deliberately split out as its own
+  slice with its own ADR (S-27 / #113) rather than folded into this infra-only fix.
+- **A documented `make local-seed` step run after `make local`.** Smallest change, but it fails the
+  slice's "no manual seeding" outcome — the local stack is exactly the one meant to just work in a
+  browser. Rejected.
+- **Fixed zaaktype UUID via OpenZaak `setup_configuration`/fixtures.** OpenZaak assigns UUIDs on POST;
+  declaratively creating a fully *published* zaaktype (statustypen + resultaattypen validated against
+  the Selectielijst + roltypen + iot relations) is not something `setup_configuration` supports
+  cleanly in 1.28.2. Rejected as more fragile than reusing `seed_catalogus.py`.

docs/architecture/adr-0021-acl-resolves-zaaktype-by-identificatie.md

@@ -0,0 +1,67 @@
+# ADR-0021: The ACL resolves its zaaktype by identificatie, not a pinned URL
+
+- **Status:** Accepted
+- **Date:** 2026-07-22
+- **Deciders:** Respellion engineering
+- **Relates to:** S-27 (#113), proposed in #117. The cleaner design deliberately split out of S-B04
+  (#110, ADR-0020), which fixed the local stack with an infra-only bootstrap.
+
+## Context
+
+The ACL was handed a **pinned zaaktype URL** (`Acl__Defaults__ZaaktypeUrl`) and diploma
+informatieobjecttype URL. OpenZaak assigns those UUIDs at creation, so the URL is not knowable when
+the compose file is written — every stack had to seed the catalogus and then capture + inject the
+resulting URLs out of band: `run-domain-check.sh` for CI, and the `local-seed` → `acl.env` bootstrap
+(ADR-0020) for `make local`. Brittle, and a stale/placeholder URL failed opaquely (OpenZaak 400).
+
+## Decision
+
+**The ACL resolves its zaaktype (by `identificatie`) and diploma informatieobjecttype (by
+`omschrijving`) from OpenZaak's Catalogi API, instead of being handed the URLs.**
+
+- **Config:** `AclDefaults.ZaaktypeUrl`/`InformatieobjecttypeUrl` → `ZaaktypeIdentificatie`
+  (`BIG-REGISTRATIE`) / `InformatieobjecttypeOmschrijving` (`Diploma`).
+- **Lookup (gateway, §8.1):** `GET /catalogi/api/v1/zaaktypen?status=definitief&identificatie=…` →
+  the published zaaktype URL; `GET /catalogi/api/v1/informatieobjecttypen?status=definitief` matched
+  on `omschrijving`. Reuses the gateway's existing catalogus-query machinery.
+- **Timing = lazy + cached (`CachedZaaktypeCatalog`).** Resolve on first use (first zaak open /
+  document store) and cache for the process lifetime. Lazy avoids a startup ordering coupling — the
+  ACL never crash-loops when it boots before the catalogus is published. A **failed** resolution is
+  not cached, so it is retried on the next call (e.g. once the zaaktype is published); a restart
+  re-resolves.
+- **Failure mode:** no published match → a clear "No published zaaktype with identificatie '…' found
+  in OpenZaak — is the BIG catalogus seeded and published?" error, replacing the opaque placeholder
+  400.
+
+## Consequences
+
+**Positive**
+
+- No stack captures or injects a server-assigned URL any more: `run-domain-check.sh` drops the
+  `ACL_ZAAKTYPE_URL`/`ACL_INFORMATIEOBJECTTYPE_URL` capture+inject, `docker-compose.yml`/`.local.yml`
+  drop the placeholder URL env, and `local-seed`/`acl.env` shrink to a single line. The ACL
+  self-configures from the catalogus it already talks to.
+- The failure mode is legible (a named error instead of a 400 on a zeros-UUID).
+
+**Negative / costs**
+
+- The ACL still needs its OpenZaak **BaseUrl** pointed at a **URL-valid host (a container IP)**, so
+  the base-URL injection from ADR-0020 stays (the local `acl.env` now carries only that; CI keeps
+  `ACL_OPENZAAK_BASEURL`). This is **not** something S-27 can remove: OpenZaak validates the
+  `zaaktype` field on zaak-create with Django's URLValidator and **rejects a single-label host**
+  (`http://openzaak:8000/…` → `zaaktype: bad-url, "Voer een geldige URL in."`, confirmed empirically).
+  So ADR-0020's `seed-env` volume + ACL entrypoint shim are **simplified, not deleted**.
+- New branching in the gateway/resolver → unit + integration test surface; the mutation ratchet
+  covers it (§5).
+- A seed step still **creates + publishes** the zaaktype (this ADR changes only discovery). Reaching
+  OpenZaak's Catalogi API to *seed* likewise needs the IP host (its query params hit the same
+  URLValidator) — unchanged from before.
+
+## Alternatives considered
+
+- **Resolve at startup** (eager). Simpler cache, but reintroduces the ordering coupling (crash-loop
+  if the catalogus isn't published yet). Rejected in favour of lazy.
+- **Per-request resolution** (no cache). No stale-cache risk, but a Catalogi lookup on every ACL
+  operation. Rejected; a process-lifetime cache with restart-to-refresh is enough here.
+- **Keep the pinned URL** (status quo / ADR-0020 only). Rejected — the brittleness this ADR removes is
+  exactly what S-27 was carved out to fix.

docs/architecture/adr-0022-quartz-scheduler.md

@@ -0,0 +1,79 @@
+# ADR-0022: Quartz.NET for time-triggered fleet sweeps
+
+- **Status:** Accepted
+- **Date:** 2026-07-23
+- **Deciders:** Respellion engineering
+- **Slice:** S-17 (#18) · **Proposal issue:** #120
+
+## Context
+
+A BIG inscription is valid for a fixed term; before it lapses the zorgprofessional
+must herregistreren. S-17 adds a **herregistratie reminder sweep**: once a day,
+scan the register for inscriptions whose deadline is within the reminder window and
+remind each one.
+
+The Domain Service already runs periodic background work — `OpenZaakJobPump`,
+`BeoordelingEscalatiePump`, `RegistratieVerlopenPump`. Those are **continuous job
+pollers**: they drain Flowable's external-task/job queues at-least-once, picking up
+work as soon as it is parked, on a short poll interval. The reminder sweep is a
+different shape of work: **time-triggered**, once a day, over our own store — there
+is no queue to drain and no "as soon as possible" requirement.
+
+The PRD already names the scheduler component: "Scheduler (Quartz.NET): fleet-wide
+sweeps (expiry, reminders)" (§39, §94). Adding Quartz.NET is nonetheless a new
+dependency, so this decision is recorded before the code lands (CLAUDE.md §14).
+
+## Decision
+
+**Use Quartz.NET for time-triggered fleet sweeps, starting with the herregistratie
+reminder sweep. Leave the existing pumps as `BackgroundService` job pollers.**
+
+- `HerregistratieReminderJob` (a Quartz `IJob`) is fired by a cron trigger — daily
+  at 03:00 by default, overridable with `Quartz__Cron`. It is a thin shell: it
+  resolves the pure `HerregistratieReminderSweep` (application layer) and logs how
+  many reminders went out.
+- The sweep's rule lives in the domain: `Registration.HerregistratieReminderDue(asOf)`,
+  which the store query and the sweep both build on. The sweep marks each reminded
+  inscription (`HerregistratieReminderVerstuurd`), so a re-fire reminds no one twice
+  (§8.6).
+
+Two options were rejected:
+
+1. **A `BackgroundService` with a 24h `Task.Delay`.** No new dependency, but it
+   drifts to process-start time, has no cron/misfire semantics, and contradicts the
+   PRD's named component. A daily "run at 03:00" is exactly what cron scheduling is
+   for.
+2. **Migrating the three pumps onto Quartz too, for one mechanism.** Rejected: the
+   pumps are not schedulers. Forcing a "run at time T" tool onto "drain this queue
+   continuously" work is churn and a boundary change for negative benefit. The
+   teachable distinction is worth keeping: **pumps drain queues; Quartz fires
+   sweeps.**
+
+## Consequences
+
+**Positive**
+
+- Cron scheduling with restart-stable timing and misfire handling, for free.
+- The reminder rule is one domain method, reused by the store query and the sweep;
+  the scheduler owns none of the policy.
+- The reference app now demonstrates the intended Scheduler component.
+
+**Negative / costs**
+
+- One new dependency (`Quartz`, `Quartz.Extensions.Hosting`) in the Domain Service.
+- Two periodic-work mechanisms coexist (pumps + Quartz). Deliberate — they model
+  two genuinely different concerns, documented here.
+
+**Follow-up**
+
+- The validity term (5 years) and reminder lead time (16 weeks) are domain
+  calibration knobs; promote them to beheer config (S-15) if a demo needs them
+  per-catalogus.
+- The Quartz job stores its schedule in RAM (`RAMJobStore`); a persistent/clustered
+  store is a later concern if the Domain Service is scaled out.
+
+## Coupling rules touched (CLAUDE.md §8)
+
+None. Quartz is internal to the Domain Service and drives an application use case
+over the store port. No ZGW or Flowable coupling is added; the sweep talks to no
+peer module.

docs/architecture/adr-0023-observability-stack.md

@@ -0,0 +1,74 @@
+# ADR-0023: Grafana-native observability stack (Tempo + Prometheus + Grafana)
+
+- **Status:** Accepted
+- **Date:** 2026-07-23
+- **Deciders:** Respellion engineering
+- **Slice:** S-16a (#122), first of the S-16 (#17) split
+
+## Context
+
+The PRD calls for "OpenTelemetry traces, Prometheus metrics; a local Grafana with
+pre-built dashboards" (§80). S-16 was split (CLAUDE.md §13) into a backplane slice
+(this one), distributed tracing (#123), and metrics + dashboards (#124). The
+backplane must stand up first: a local, CI-friendly place for traces and metrics to
+land, viewable in one UI, reaching green health within the 3-minute compose budget.
+
+Two shape decisions are non-obvious enough to record.
+
+## Decision
+
+**Run a Grafana-native stack — Grafana Tempo (traces) + Prometheus (metrics) +
+Grafana (UI) — with the services exporting OTLP straight to Tempo (no collector),
+and ship the config baked into small built images.**
+
+### Trace backend: Tempo (not Jaeger)
+
+Tempo keeps everything under one Grafana pane alongside metrics (and later logs),
+which is exactly the "local Grafana with dashboards" the PRD asks for. Jaeger would
+add a second UI and a second mental model for no benefit at this scale.
+
+### No OTLP collector
+
+Tempo ingests OTLP directly (gRPC 4317 / HTTP 4318) and Prometheus scrapes each
+service's `/metrics`, so a collector would be a hop that processes nothing. Skipped.
+If we later need fan-out, tail sampling, or log processing, a collector is an
+additive change — the services already speak OTLP.
+
+### Config baked into built images, not config volumes
+
+The upstream Common Ground modules (OpenZaak, NRC, Keycloak, Flowable) run as
+**verbatim** images and get their config streamed into external named volumes by
+`infra/seed-config.sh`, because bind mounts don't reach sibling containers on the
+CI runner (see `docs/runbooks/gitea-actions-gotchas.md`). The observability tools
+are **not** peer modules we must run verbatim, so we take the simpler path: a
+three-line `Dockerfile` per tool that `COPY`s its config in. This reaches sibling
+containers everywhere (docker, podman, CI) with no seed step, no `CFG_VOLS` entry,
+and no Makefile sprawl.
+
+### Verified, not assumed
+
+`infra/run-observability-check.sh` (the `verify-observability` step, run early in CI
+`verify-stack`) asks Grafana to reach both datasources — Prometheus via its health
+method, Tempo via the datasource proxy (Tempo's Grafana plugin implements no health
+method) — so the check proves the datasources are actually wired, not merely that
+containers started. The containers are not in `WAIT_SVCS`; the check polls Grafana
+itself, so no in-image healthcheck tool is required.
+
+## Consequences
+
+**Positive**
+
+- One UI for traces + metrics + (future) logs. Config is versioned in
+  `infra/observability/` and self-contained in the images.
+- Backplane is independent of app instrumentation — #123 and #124 build on it.
+
+**Negative / costs**
+
+- Three more images built each CI run (kept small; not on the health-gate list).
+- Storage is ephemeral container fs — a demo backplane, not a retention target.
+  Object storage for Tempo / remote-write for Prometheus is a later concern.
+
+## Coupling rules touched (CLAUDE.md §8)
+
+None. The stack is passive infrastructure: services *push* OTLP and *expose*
+`/metrics`; nothing in the stack calls into a service or a peer module.

docs/architecture/adr-0024-prometheus-aspnetcore-exporter.md

@@ -0,0 +1,53 @@
+# ADR-0024: Expose OTel metrics with the (prerelease) Prometheus AspNetCore exporter
+
+- **Status:** Accepted
+- **Date:** 2026-07-24
+- **Deciders:** Respellion engineering
+- **Slice:** S-16c (#124), last of the S-16 (#17) split
+
+## Context
+
+ADR-0023 already fixed the shape of metrics collection: **Prometheus scrapes each
+service's `/metrics`** (pull, no collector). S-16c implements it. That needs a package
+that turns the OpenTelemetry `MeterProvider` into a Prometheus scrape endpoint inside
+ASP.NET Core. The canonical one is `OpenTelemetry.Exporter.Prometheus.AspNetCore`
+(`AddPrometheusExporter()` + `app.MapPrometheusScrapingEndpoint()`).
+
+The catch: that exporter has **never had a stable release** — the whole OTel .NET
+Prometheus exporter line is versioned `-beta` (we pin `1.17.0-beta.1`, matched to the
+`1.17.0` core we already use). Adding it is a new dependency (CLAUDE.md §14), and taking
+a prerelease package into all five services is the decision worth recording.
+
+## Decision
+
+**Add `OpenTelemetry.Exporter.Prometheus.AspNetCore` `1.17.0-beta.1` to the five .NET
+services and expose `/metrics` with it.**
+
+- What it gives us: the OTel-native pull endpoint, so the meters we already register for
+  tracing-adjacent instrumentation surface as Prometheus text with zero extra plumbing.
+- What we'd write to replace it: a hand-rolled `IMetricsListener`/`MeterListener` that
+  formats Prometheus exposition text — real work, and a reimplementation of a widely-used
+  library for no gain.
+- Risk it adds: a prerelease API that can shift between betas. Contained: it is only
+  wired in `Program.cs` (two calls per service, excluded from mutation), the version is
+  pinned, and `verify-metrics` proves the endpoint + scrape actually work each CI run.
+
+The alternative — pushing metrics over OTLP to a collector that re-exposes them — was
+already rejected in ADR-0023 (no collector hop). Not revisited here.
+
+## Consequences
+
+**Positive**
+
+- Golden-signal metrics on `/metrics` with the standard OTel names
+  (`http_server_request_duration_seconds`, `dotnet_*`), scraped straight by Prometheus.
+- No collector, no bespoke exposition code.
+
+**Negative / costs**
+
+- A `-beta` package in production services. Mitigated by the pin + the `verify-metrics`
+  CI gate; upgrading tracks the OTel core version bumps.
+
+## Coupling rules touched (CLAUDE.md §8)
+
+None. Metrics are passive: Prometheus pulls; no service calls into the stack.

docs/architecture/adr-0025-bff-reads-catalogus-via-acl.md

@@ -0,0 +1,58 @@
+# ADR-0025: The BFF reads the catalogus directly from the ACL
+
+- **Status:** Accepted
+- **Date:** 2026-07-24
+- **Deciders:** Respellion engineering
+- **Slice:** S-15a (#130), first of the S-15 (#16) split
+
+## Context
+
+The beheer portal shows a read-only view of the ZTC catalogus (the published
+zaaktypen). Two coupling rules constrain where that data can come from:
+
+- **§8.1** — only the ACL may talk to the ZGW APIs (Catalogi included). So the
+  catalogus read *must* originate in the ACL.
+- **§8.3** — portals talk only to the BFF. So the portal reaches the ACL only
+  through the BFF.
+
+That leaves the question of *how the BFF gets the data*. Until now the BFF fanned
+out to exactly two backends — the Domain Service and the read projection. The
+catalogus is neither: it is not a registration (domain) nor a projected read model.
+
+## Decision
+
+**The BFF calls the ACL directly for the beheer catalogus read** — a new typed
+`IAclClient` (`GET /catalogi/zaaktypen`), configured by `Downstream:Acl:BaseUrl`,
+mirroring the existing `IDomainClient` / `IProjectionClient` pattern.
+
+Rejected alternative — **route it through the Domain Service** (BFF → domain →
+ACL): the catalogus is not a domain concern, so the domain would gain a
+pass-through endpoint that owns no aggregate and no invariant, blurring the
+domain's responsibility purely to avoid a new edge. That is worse coupling, not
+better.
+
+This adds one service-to-service edge (BFF → ACL) — an architecturally
+significant boundary change (§14), hence this ADR. It does **not** bend §8: the
+ACL stays the only code that reads ZGW, and the portal still talks only to the
+BFF. The ACL endpoint is a plain read that trusts its callers (§8.3); the
+beheerder authorization lives at the BFF (medewerker realm + `beheerder` role).
+
+## Consequences
+
+**Positive**
+
+- The catalogus read follows the shortest honest path; the domain stays about
+  registrations.
+- Symmetric with the other downstream clients — nothing new to learn.
+
+**Negative / costs**
+
+- The BFF now depends on three backends instead of two. The ACL must be reachable
+  for the beheer portal to load (it already is — the BFF is on the same network).
+- A second consumer of the ACL (alongside the domain and event-subscriber), so
+  ACL read endpoints are now part of more than one caller's contract.
+
+## Coupling rules touched (CLAUDE.md §8)
+
+A new BFF → ACL edge. §8.1 and §8.3 remain intact; §14 (boundary change) is the
+reason this ADR exists.

docs/demo-script.md

@@ -5,6 +5,212 @@ copy-pasteable walkthrough against a local `make up` stack.
 
 ---
 
+## S-15a — Beheer-portal: read-only catalogus viewer (#130, ADR-0025)
+
+**Outcome:** a new **beheer** portal (medewerker realm, like behandel) shows the ZTC catalogus —
+the published zaaktypen — **read-only**. A beheerder logs in and sees the seeded BIG-REGISTRATIE
+zaaktype. The read path is portal → BFF `GET /beheer/catalogi/zaaktypen` (medewerker realm +
+`beheerder` role) → ACL `GET /catalogi/zaaktypen` → ZGW Catalogi API. The BFF reaches the ACL
+directly (ADR-0025); managing the default-fill config (S-15b) and MFA (S-15c) come next.
+
+```bash
+make up
+# 1. Log in as bram-beheerder / test123 → the catalogus lists the published zaaktypen.
+open http://localhost:8143
+#
+# 2. Automated (a CI verify-stack e2e): a beheerder logs in and sees BIG-REGISTRATIE.
+make verify-e2e        # → catalogus.spec: "a beheerder sees the published zaaktypen in the catalogus"
+#
+# 3. The BFF endpoint is behind the beheerder role — a plain behandelaar gets 403 (BFF unit tests):
+#    Bff.Tests → BeheerEndpointTests.
+```
+
+**Auth:** the `beheerder` realm role + `bram-beheerder` user live in the medewerker realm
+(`infra/keycloak/realms/medewerker-realm.json`); the BFF reuses the medewerker bearer scheme and its
+realm-role lifting, requiring `beheerder` rather than `behandelaar`.
+
+---
+
+## S-16c — Prometheus metrics + golden-signal Grafana dashboard (#124, ADR-0023)
+
+**Outcome:** the five .NET services now expose OpenTelemetry metrics in Prometheus format at `/metrics`
+— ASP.NET Core + `HttpClient` instrumentation plus the built-in `System.Runtime` meter. Prometheus
+scrapes each service (one job per service), and a **pre-built Grafana dashboard** — *Request path —
+golden signals* — plots the four golden signals: **traffic** (req/s), **errors** (5xx/s), **latency**
+(p95 request duration), and **saturation** (CPU cores in use), split by service. It populates under load.
+
+```bash
+# 1. Automated (a CI verify-stack step): generate BFF traffic and assert Prometheus scraped the
+#    golden-signal metric from every service.
+make verify-metrics              # → OK — targets up: [...]; request metric scraped from: [...]
+
+# 2. By hand: drive the stack, generate some load, then open the dashboard.
+make up
+for i in $(seq 1 50); do curl -s localhost:8080/openbaar/register >/dev/null; done   # BFF → projection-api
+open http://localhost:3000       # Grafana → Dashboards → "Request path — golden signals"
+open http://localhost:9090/targets   # Prometheus → every service target UP
+```
+
+**The path:** each host adds `.WithMetrics(AddAspNetCoreInstrumentation + AddHttpClientInstrumentation +
+AddMeter("System.Runtime") + AddPrometheusExporter)` and maps `/metrics`; Prometheus scrapes
+`<service>:8080/metrics` (config in `infra/observability/prometheus/prometheus.yml`); Grafana ships the
+dashboard via provisioning against the fixed `prometheus` datasource uid. No metrics are pushed over
+OTLP — Prometheus pulls, so there is no collector hop (ADR-0023).
+
+---
+
+## S-16b — distributed traces across the .NET services (#123, ADR-0023)
+
+**Outcome:** the five .NET services (BFF, Domain, ACL, projection-api, event-subscriber) now emit
+OpenTelemetry traces — ASP.NET Core + `HttpClient` auto-instrumentation, exported over OTLP to Tempo.
+Because every cross-service call goes through a typed `HttpClient`, the W3C `traceparent` propagates for
+free, so a request is **one connected trace** across the services (bff → domain → acl → openzaak;
+bff → projection-api). `/health` is filtered out. No browser-side instrumentation yet, so the trace
+begins at the BFF; the async Flowable-poll boundary is a separate trace (ADR-0023).
+
+```bash
+# 1. Automated (a CI verify-stack step): generate BFF traffic and assert Tempo holds one trace
+#    spanning multiple services.
+make verify-tracing              # → OK — trace <id> spans ['bff', 'projection-api']
+
+# 2. By hand: drive the stack, then explore traces in Grafana.
+make up
+curl -s localhost:8080/openbaar/register >/dev/null   # BFF → projection-api
+open http://localhost:3000       # Grafana → Explore → Tempo → Search → service.name = bff → open a trace
+```
+
+**The path:** each host wires `AddOpenTelemetry().WithTracing(AddAspNetCoreInstrumentation +
+AddHttpClientInstrumentation + AddOtlpExporter)`; `OTEL_SERVICE_NAME` / `OTEL_EXPORTER_OTLP_ENDPOINT`
+come from compose; spans export to **tempo:4317** and render in Grafana against the provisioned Tempo
+datasource.
+
+---
+
+## S-16a — observability backplane: Tempo + Prometheus + Grafana (#122, ADR-0023)
+
+**Outcome:** the compose stack now includes a Grafana-native observability backplane — **Tempo** (OTLP
+trace ingest on 4317/4318), **Prometheus**, and **Grafana** with both datasources auto-provisioned.
+Nothing is instrumented yet (traces land in S-16b, metrics + dashboards in S-16c); this slice stands the
+backplane up and proves Grafana can reach both datasources. Config is baked into small built images
+(`infra/observability/`) — no collector, no config-volume seeding.
+
+```bash
+# 1. Bring the stack up, then assert the backplane is live (Grafana healthy + Tempo/Prometheus
+#    datasources reachable through Grafana). This is a CI verify-stack step.
+make up
+make verify-observability        # → ✓ Grafana healthy  ✓ Prometheus reachable  ✓ Tempo reachable
+
+# 2. Or just the backplane, no full stack needed (no external egress):
+docker compose -f infra/docker-compose.yml up -d --build tempo prometheus grafana
+open http://localhost:3000        # Grafana (admin/admin) → Connections → Data sources: Prometheus + Tempo
+open http://localhost:9090        # Prometheus
+```
+
+**The path:** services will export OTLP → **Tempo:4317** and expose `/metrics` ← **Prometheus** scrapes;
+**Grafana** (:3000) reads both via provisioned datasources with fixed uids `tempo` / `prometheus`.
+
+---
+
+## S-17 — herregistratie reminder sweep on a Quartz cron (#18, ADR-0022)
+
+**Outcome:** an inscription (INGESCHREVEN) now carries the moment it was entered in the register, from
+which its herregistratie deadline is derived (inscription + 5-year validity). A **Quartz.NET** cron job
+in the Domain Service sweeps once a day (03:00, overridable via `Quartz__Cron`): every inscription
+inside the 90-day window before its deadline is flagged `HerregistratieReminderVerstuurd` and logged.
+The sweep is idempotent — a re-fire reminds no one twice — and is a deliberately different mechanism
+from the queue-draining pumps (Quartz fires time-triggered sweeps; pumps drain Flowable queues,
+ADR-0022). There is no outbound notification in v1: the reminder is the flag on the aggregate plus a
+log line.
+
+```bash
+# 1. The domain unit tests prove the rule and the sweep end to end (rule → store query → sweep):
+cd services/domain && dotnet test Big.Tests/Big.Tests.csproj \
+  --filter "FullyQualifiedName~Herregistratie|FullyQualifiedName~ReminderSweep"
+#    → the reminder is due once the 90-day window opens, not before; a reminded inscription is skipped
+#      on the next sweep; the sweep flags + persists every due inscription and returns their ids.
+
+# 2. The read model surfaces the deadline once a registration is approved — the field the sweep acts on:
+curl -s localhost:8000/registrations/<id> | jq '{status, herregistratieVoor, herregistratieReminderVerstuurd}'
+#    → after approval: herregistratieVoor is inscription + 5 years; the flag flips true once swept.
+```
+
+**The path:** `Registration.Approve(now)` stamps `IngeschrevenOp` → daily Quartz `HerregistratieReminderJob`
+→ `HerregistratieReminderSweep` → `IRegistrationStore.FindDueForHerregistratieReminderAsync` (filtered by
+the aggregate's own `HerregistratieReminderDue` rule) → `MarkHerregistratieReminderVerstuurd` + log.
+
+---
+
+## S-B04 — `make local` completes the whole flow with no manual seeding (#110, ADR-0020)
+
+**Outcome:** the host-browser stack (`make local`) now self-seeds at bring-up — it publishes the BIG
+zaaktype and wires the ACL to it, deploys the `diploma-eligibility` DMN, and registers the NRC
+abonnement — so a fresh bring-up runs submit → werkbak → openbaar without the manual seeding the
+`verify-*` scripts do for CI. (Previously the process stuck at `OpenZaakAanmaken`, the werkbak stayed
+empty, and the openbaar register showed nothing.)
+
+```bash
+# 1. Fresh bring-up (self-seeding init containers: local-seed, nrc-subscribe; DMN in flowable-init).
+make local
+
+# 2. Assert the whole flow works with no manual seeding — submit opens a zaak, documents route it to
+#    the werkbak, and the reference appears in the openbaar register:
+make verify-local     # → "OK — a fresh local stack completed the flow with no manual seeding ..."
+
+# 3. Or by hand in the browser: log in at http://localhost:8140 (jan-burger / test123), submit +
+#    upload a PDF, then approve it in the werkbak at http://localhost:8142 (merel-behandelaar /
+#    test123); it shows as INGESCHREVEN in the openbaar register at http://localhost:8141.
+```
+
+> The zaaktype is discovered by the ACL itself since S-27 (below); `local-seed`'s `acl.env` now
+> carries only OpenZaak's IP base URL, which the ACL still needs because OpenZaak rejects a
+> single-label host on zaak-create (ADR-0020 + ADR-0021).
+
+---
+
+## S-27 — ACL resolves its zaaktype by identificatie, not a pinned URL (#113, ADR-0021)
+
+**Outcome:** the ACL discovers its BIG zaaktype (by `identificatie`) and diploma informatieobjecttype
+(by `omschrijving`) from OpenZaak's Catalogi API, instead of being handed the server-assigned URLs.
+No user-visible behaviour change — the flow runs exactly as before — but no stack captures/injects a
+zaaktype URL any more, and a missing catalogus now fails with a clear message instead of an opaque 400.
+
+```bash
+# The live ACL↔OpenZaak integration test proves resolution against a real seeded OpenZaak:
+make verify-acl     # → "resolves the published BIG-REGISTRATIE zaaktype + Diploma informatieobjecttype by business key"
+
+# End-to-end unchanged (the ACL self-discovers the zaaktype during the flow):
+make verify-local   # local stack — still green, now with no zaaktype-URL injection
+make verify-domain  # CI stack — recreates the ACL pointed only at OpenZaak's IP (no URL to inject)
+```
+
+> The ACL still needs its OpenZaak base URL at a URL-valid host (a container IP): OpenZaak's
+> URLValidator rejects a single-label host like `openzaak:8000` on zaak-create. So ADR-0020's base-URL
+> injection stays; only the zaaktype/informatieobjecttype **URL** injection is gone (ADR-0021).
+
+---
+
+## S-08d — Walking skeleton complete: browser → submit, end-to-end
+
+**Outcome:** the self-service portal is served in the stack and the full front-of-house happy path
+runs in a real browser — **mock DigiD login → submit → confirmation** — closing the walking skeleton
+(portal → BFF → domain → Flowable → ACL → OpenZaak, with the openbaar register reading the projection).
+
+```bash
+# 1. Bring the whole stack up (portal served on :8140, BFF :8080, Keycloak :8180).
+make up
+
+# 2. Automated happy path — Playwright, inside the compose network (issuer-consistent):
+make verify-e2e          # → login as jan-burger → submit → "ontvangen" confirmation
+
+# 3. By hand: open the portal, log in as jan-burger / test123, click "Registratie indienen".
+open http://localhost:8140
+```
+
+> The portal is served same-origin with the BFF (nginx proxies `/self-service` + `/openbaar`), so no
+> CORS; the OIDC authority comes from `/config.json` at runtime. See `docs/frontend-decisions.md`.
+
+---
+
 ## S-08c — Self-service submit form (NL Design System + DigiD)
 
 **Outcome:** a zorgprofessional logs in via mock DigiD and submits a BIG registration through the
@@ -146,3 +352,317 @@ curl -fsS http://localhost:8120/register | jq 'length'  # → unchanged
 
 > `bsn` / `naam_placeholder` are deferred (ADR-0008) — the notification doesn't carry them and
 > the subscriber may not read OpenZaak directly (§8.1). They surface in a later slice.
+
+---
+
+## S-09 — Openbaar Register portal (public visibility)
+
+**Outcome:** the entry a zorgprofessional submits via self-service becomes publicly visible in the
+anonymous openbaar register portal — closing the walking-skeleton loop (submit → process → projection
+→ public visibility).
+
+**The path:** self-service submit → BFF → domain → (zaak) OpenZaak → NRC → Event Subscriber →
+projection → openbaar portal reads the BFF's public-safe `GET /openbaar/register`.
+
+```bash
+# 1. Bring the full stack up (self-service :8140, openbaar :8141).
+make up
+
+# 2. Submit a registration via the self-service portal (mock DigiD: jan-burger / test123),
+#    or drive the whole happy path automatically (login → submit → public visibility):
+make verify-e2e
+
+# 3. Open the public register — no login. It lists the submitted entry (id + status only).
+#    Only public-safe fields cross the BFF: bsn / naam never appear.
+open http://localhost:8141/            # search box; searches the BFF by referentie
+curl -fsS http://localhost:8140/openbaar/register | jq   # same public-safe view via the BFF proxy
+# → [ { "id": "<zaak-uuid>", "status": "INGEDIEND" } ]
+```
+
+> The register shows `INGEDIEND` on submit; approval flips it to `INGESCHREVEN` — see S-09b below.
+
+---
+
+## S-09b — Approval flow (public visibility flips to INGESCHREVEN)
+
+**Outcome:** a behandelaar approves a submitted registration via a temporary admin endpoint (no
+behandel-portal yet — S-12). The approval sets the zaak's final status through the ACL, which flows
+back to the projection over NRC, and the openbaar register then shows the entry as `INGESCHREVEN`.
+
+**The path:** `POST /registrations/{id}/approve` (domain) → ACL sets the zaak eindstatus (ZGW
+`/statussen`) → OpenZaak → NRC → Event Subscriber projects `INGESCHREVEN` → openbaar register.
+
+```bash
+# 1. Full stack up, then drive submit → public INGEDIEND → approve → public INGESCHREVEN:
+make up
+make verify-e2e
+
+# 2. Or by hand: submit (as in S-09), note the reference, then approve it.
+#    The zaak is opened off the request path, so approve once GET shows a zaakUrl.
+ref="<registration-reference-from-the-confirmation>"
+curl -fsS http://localhost:8130/registrations/$ref | jq       # domain (host port 8130): wait for .zaakUrl
+curl -fsS -X POST http://localhost:8130/registrations/$ref/approve -i   # → 204 No Content
+
+# 3. The public register now shows the entry as approved.
+curl -fsS http://localhost:8140/openbaar/register | jq
+# → [ { "id": "<zaak-uuid>", "status": "INGESCHREVEN" } ]
+```
+
+> **End of walking skeleton** (S-09 + S-09b): submit → process → projection → public visibility, from
+> INGEDIEND through approval to INGESCHREVEN. The subscriber takes any post-creation status-set as the
+> approval (ADR-0011) — a walking-skeleton assumption that tightens when more transitions arrive (S-12+).
+
+## #78 — One reference across both portals (ADR-0012)
+
+Before this change the self-service confirmation and the openbaar register showed **different**
+identifiers, so a citizen could not look their registration back up. Now both show the same
+**reference**: the domain `registrationId` is set as the zaak's `identificatie` by the ACL, and the
+Event Subscriber enriches the projection with it by reading the zaak through the ACL (§8.1) — storing
+it in the replay log so rebuild stays log-only (ADR-0008).
+
+**The path:** domain passes `registrationId` → ACL sets it as `zaak.identificatie` → NRC →
+Event Subscriber asks the ACL for the reference → projection row + replay log → openbaar register.
+
+```bash
+# Submit as in S-09 and note the reference on the confirmation, then find it in the public register:
+ref="<registration-reference-from-the-confirmation>"
+curl -fsS "http://localhost:8140/openbaar/register?q=$ref" | jq
+# → [ { "id": "<zaak-uuid>", "status": "INGEDIEND", "reference": "<same-ref-as-confirmation>" } ]
+```
+
+> The openbaar register's "Referentie" column and its search now use this reference — the exact value
+> the citizen saw on submit. Asserted end-to-end by the Playwright happy path.
+
+## S-12 — Behandel portal: werkbak + beoordeling (#13, ADR-0013)
+
+A behandelaar now works submitted registrations in a real portal instead of the temporary admin
+endpoint. After a citizen submits (as above), the workflow parks the registration at the Flowable
+`Beoordelen` user task, and it shows up in the **werkbak**. The behandelaar logs in against the
+Keycloak `medewerker` realm and decides — **goedkeuren** (→ INGESCHREVEN via the ACL, per ADR-0011)
+or **afwijzen** — which also completes the Beoordelen task so the process advances.
+
+```text
+# 1. Open the behandel portal and log in as a behandelaar (medewerker realm):
+#    http://localhost:8142/   →  merel-behandelaar / test123
+#
+# 2. The werkbak lists the registrations awaiting beoordeling (referentie / bsn / status).
+#    Find the reference from the submit confirmation and click "Goedkeuren" on that row.
+#
+# 3. The row drops off the werkbak (its Beoordelen task is completed) and the openbaar register
+#    (http://localhost:8141/) now shows that reference as INGESCHREVEN.
+```
+
+**The path:** behandel portal → BFF `POST /behandel/registrations/{id}/decide` (behandelaar policy,
+`medewerker` realm) → domain applies the decision + completes the Flowable `Beoordelen` task →
+ACL → NRC → event-subscriber → projection → openbaar register shows INGESCHREVEN.
+
+> The full round-trip — DigiD submit → public INGEDIEND → behandelaar goedkeurt in the werkbak →
+> public INGESCHREVEN — is the Playwright happy path (`tests/e2e/registration.spec.ts`), which now
+> drives the behandel portal in place of the old admin endpoint.
+
+## S-11 — Withdrawal: "trek aanvraag in" (#12, ADR-0014)
+
+A zorgprofessional can withdraw their own still-open registration from the self-service portal. The
+withdrawal is owner-scoped (the BFF forwards the DigiD token's bsn; the domain only lets the owner
+withdraw) and cancels the running workflow via a BPMN message event, so the case leaves the
+behandelaar's werkbak.
+
+```text
+# 1. Log in and submit at the self-service portal (http://localhost:8140/, jan-burger / test123),
+#    note the "Referentie" on the confirmation.
+# 2. Click "Trek aanvraag in" → the page confirms the registration is ingetrokken.
+# 3. In the behandel werkbak (http://localhost:8142/, merel-behandelaar) the registration no longer
+#    appears — its Beoordelen task was cancelled.
+```
+
+**The path:** self-service → BFF `POST /self-service/registrations/{id}/withdraw` (DigiD, owner-scoped)
+→ domain sets INGETROKKEN + correlates the `RegistratieIngetrokken` message to the process → the
+interrupting boundary event ends it → the werkbak drops the case.
+
+> DigiD submit → trek aanvraag in → ingetrokken is the Playwright happy path
+> (`tests/e2e/withdrawal.spec.ts`); the owner-scoping + workflow cancellation are covered by the
+> `Een registratie intrekken` acceptance scenarios and the domain live check.
+
+## S-14 — Beoordeling escalation: 14 days unclaimed → teamlead (#15, ADR-0015)
+
+A beoordeling a behandelaar does not pick up within 14 days escalates to the teamlead. A
+non-interrupting boundary timer on the `Beoordelen` task fires a `BeoordelingEscaleren` external task;
+the domain's escalation worker reassigns the still-open task's candidate group from `behandelaar` to
+`teamlead`, so it moves from the behandelaar werkbak into the teamlead's. The `Beoordelen` task keeps
+its identity throughout — only who may claim it changes.
+
+The timer is 14 days, so the demo fires it early through Flowable's management API (exactly what the
+verify-domain check automates):
+
+```bash
+# 1. Submit at the self-service portal (http://localhost:8140/, jan-burger / test123). The case
+#    parks at Beoordelen, visible in the behandelaar werkbak (http://localhost:8142/, merel-behandelaar)
+#    but NOT claimed.
+#
+# 2. Find the parked instance and its Beoordelen task, then fire the boundary timer early:
+FL=http://localhost:8090/flowable-rest/service
+PID=$(curl -s -u rest-admin:test -X POST "$FL/query/tasks" -H 'Content-Type: application/json' \
+  -d '{"processDefinitionKey":"registratie","taskDefinitionKey":"Beoordelen"}' \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["processInstanceId"])')
+TID=$(curl -s -u rest-admin:test -X POST "$FL/query/tasks" -H 'Content-Type: application/json' \
+  -d '{"processDefinitionKey":"registratie","taskDefinitionKey":"Beoordelen"}' \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["id"])')
+TJ=$(curl -s -u rest-admin:test "$FL/management/timer-jobs?processInstanceId=$PID" \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["id"])')
+curl -s -u rest-admin:test -X POST "$FL/management/timer-jobs/$TJ" \
+  -H 'Content-Type: application/json' -d '{"action":"move"}'
+AJ=$(curl -s -u rest-admin:test "$FL/management/jobs?processInstanceId=$PID" \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["id"])')
+curl -s -u rest-admin:test -X POST "$FL/management/jobs/$AJ" \
+  -H 'Content-Type: application/json' -d '{"action":"execute"}'
+#
+# 3. Within a couple of poll cycles the task's candidate group flips to teamlead:
+curl -s -u rest-admin:test "$FL/runtime/tasks/$TID/identitylinks"   # → [{"group":"teamlead","type":"candidate"}]
+```
+
+**The path:** BPMN non-interrupting `P14D` boundary timer on `Beoordelen` → `BeoordelingEscaleren`
+external task → domain escalation worker (`BeoordelingEscalatiePump`) → Workflow Client swaps the task's
+candidate group behandelaar → teamlead (§8.2).
+
+> Both branches (escalate after 14 days; no-op when completed in time) are covered by the
+> `Een beoordeling escaleren` acceptance scenarios and the Workflow Client unit tests; the timer firing
+> and reassignment are asserted live by the verify-domain check.
+
+## S-13 — Diploma-eligibility: foreign diplomas route through CBGV-advies (#14, ADR-0016)
+
+A registration's diploma origin decides its route. A DMN service task in the registratie
+process evaluates the `diploma-eligibility` decision on the `diplomaOrigin` start variable: a
+**foreign** (Buitenlands) diploma is routed through an extra **CBGV-advies** user task before
+beoordeling; a **domestic** (Binnenlands) one goes straight to beoordeling. The decision lives in the
+DMN, not in code — a beheerder can read and adjust the decision table directly.
+
+The self-service portal's eIDAS→foreign wiring is a later slice; for now the origin is submitted to
+the domain directly, so the demo drives it through the domain endpoint:
+
+```bash
+# 1. Submit a foreign-diploma registration to the domain (note the returned Location/reference):
+DOM=http://localhost:8080   # domain service
+curl -s -i -X POST "$DOM/registrations" -H 'Content-Type: application/json' \
+  -d '{"bsn":"123456782","diplomaOrigin":"Buitenlands"}' | grep -i '^location:'
+#
+# 2. Once the zaak is opened, the process first parks at WachtOpDocumenten (S-10a); complete that task
+#    (documents received) — then it parks at the CBGV-advies task (NOT Beoordelen). In Flowable:
+FL=http://localhost:8090/flowable-rest/service
+curl -s -u rest-admin:test -X POST "$FL/query/tasks" -H 'Content-Type: application/json' \
+  -d '{"processDefinitionKey":"registratie","taskDefinitionKey":"CBGVAdvies"}' | python3 -m json.tool
+#
+# 3. Complete the CBGV-advies task; the case then advances to the regular Beoordelen task:
+TID=$(curl -s -u rest-admin:test -X POST "$FL/query/tasks" -H 'Content-Type: application/json' \
+  -d '{"processDefinitionKey":"registratie","taskDefinitionKey":"CBGVAdvies"}' \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["id"])')
+curl -s -u rest-admin:test -X POST "$FL/runtime/tasks/$TID" \
+  -H 'Content-Type: application/json' -d '{"action":"complete"}'
+# A domestic submission (default, or "Binnenlands") skips CBGV-advies and parks straight at Beoordelen.
+```
+
+**The path:** domain sets the `diplomaOrigin` start variable → registratie process DMN
+DMN service task sets `route` → exclusive gateway → foreign: `CBGVAdvies` user task → `Beoordelen`;
+domestic: `Beoordelen` directly (§8.2, ADR-0016).
+
+> The domestic/foreign paths are covered by the `Een diploma op herkomst routeren` acceptance
+> scenarios and unit tests (the origin is carried into the process); the DMN decision and the
+> foreign→CBGV routing are asserted live by the verify-domain check.
+
+## S-10a — Document wait + 30-day timeout cancels the registration (#102, ADR-0017)
+
+After the zaak is opened the registratie process parks at a **WachtOpDocumenten** user task, waiting
+for the citizen's documents (their diploma). Two things can happen:
+
+- **Documents arrive in time** → the task completes and the process continues to the diploma-eligibility
+  routing (S-13) → beoordeling.
+- **30 days pass with no documents** → an interrupting `P30D` boundary timer cancels the wait, runs the
+  `RegistratieVerlopen` external task, and the domain expires the registration to the terminal status
+  **VERLOPEN** (the case is cancelled).
+
+The "documents received" trigger is wired end-to-end in S-10a: the self-service page shows a
+**"Documenten aanleveren"** button after submit (portal → BFF → domain → completes the wait). S-10b
+turns that into a real file upload stored in the ZGW Documenten API via the ACL. The timeout branch is
+demonstrated by firing the 30-day timer early via the management API.
+
+```bash
+DOM=http://localhost:8080                      # domain service
+FL=http://localhost:8090/flowable-rest/service # flowable-rest
+
+# 1. Submit a registration; once the zaak is opened it parks at WachtOpDocumenten:
+curl -s -i -X POST "$DOM/registrations" -H 'Content-Type: application/json' \
+  -d '{"bsn":"123456782"}' | grep -i '^location:'          # note the /registrations/<id> reference
+WQ='{"processDefinitionKey":"registratie","taskDefinitionKey":"WachtOpDocumenten"}'
+
+# 2a. Documents-in-time: complete the WachtOpDocumenten task → the process advances to beoordeling.
+TID=$(curl -s -u rest-admin:test -X POST "$FL/query/tasks" -H 'Content-Type: application/json' \
+  -d "$WQ" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["id"])')
+curl -s -u rest-admin:test -X POST "$FL/runtime/tasks/$TID" \
+  -H 'Content-Type: application/json' -d '{"action":"complete"}'
+
+# 2b. Timeout: instead of completing it, fire the 30-day timer early via the management API. Find the
+#     instance's timer job, "move" it to executable; the async executor fires the interrupting event.
+PID=$(curl -s -u rest-admin:test -X POST "$FL/query/tasks" -H 'Content-Type: application/json' \
+  -d "$WQ" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["processInstanceId"])')
+JID=$(curl -s -u rest-admin:test "$FL/management/timer-jobs?processInstanceId=$PID" \
+  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"][0]["id"])')
+curl -s -u rest-admin:test -X POST "$FL/management/timer-jobs/$JID" \
+  -H 'Content-Type: application/json' -d '{"action":"move"}'
+#     The RegistratieVerlopen worker then expires the aggregate — read it back as VERLOPEN:
+curl -s "$DOM/registrations/<id>"   # → {"status":"Verlopen", ...}
+```
+
+**The path:** registratie process parks at `WachtOpDocumenten` → documents received completes it (→
+routing → `Beoordelen`), OR the `P30D` interrupting timer fires → `RegistratieVerlopen` external task
+→ domain worker expires the aggregate to `Verlopen` → `endVerlopen` (§8.2, ADR-0017).
+
+> Both branches are covered by the `Een documenttermijn laten verlopen` acceptance scenarios (worker +
+> aggregate) and unit tests; the wait completion and the 30-day timer firing are asserted live by the
+> verify-domain check.
+
+## S-10b — Diploma upload stored in the ZGW Documenten API (#103, ADR-0018)
+
+The self-service "Documenten aanleveren" action (S-10a) is now a **real file upload**: after submitting,
+the citizen picks a PDF and uploads it. The portal base64-encodes the file client-side and posts it to
+the BFF; the BFF forwards it to the domain, which stores it via the **ACL** as a ZGW
+`enkelvoudiginformatieobject` in the **Documenten (DRC) API** and relates it to the zaak — then completes
+the `WachtOpDocumenten` wait so beoordeling can proceed. Per §8.1 only the ACL talks to ZGW.
+
+```bash
+make up
+# 1. Log in as jan-burger / test123, submit, then — once the openbaar register shows the row —
+#    choose a PDF under "Documenten aanleveren" and upload it. The page confirms "aangeleverd".
+open http://localhost:8140
+#
+# 2. Automated: the walking-skeleton e2e now uploads a real PDF before the behandelaar approves.
+make verify-e2e
+#
+# 3. The ACL integration test proves the document is really created in the Documenten API and
+#    related to the zaak (against a live OpenZaak):
+make verify-acl        # → "Storing a diploma creates a real informatieobject related to the zaak"
+```
+
+**The path:** portal (base64) → BFF `POST /self-service/registrations/{id}/documents` → domain
+`ProvideDocuments` → ACL `POST /documenten` → ZGW `enkelvoudiginformatieobjecten` +
+`zaakinformatieobjecten`; the wait is then completed and the case advances to Beoordelen (§8.1, ADR-0018).
+
+## S-10c — the ZGW zaak is cancelled when the document term lapses (#106)
+
+When the 30-day document term lapses (S-10a), the domain no longer only marks the aggregate `Verlopen` —
+it now also cancels the **ZGW zaak** through the ACL, so OpenZaak and the register agree. The zaak is set
+to a distinct, non-terminal **`Geannuleerd`** status with a **`Vervallen`** resultaat (as opposed to the
+approval `Afgehandeld` + `Geregistreerd`), resolved by name in the ACL (§8.1, ADR-0019).
+
+```bash
+# 1. The ACL integration test proves cancellation records the Geannuleerd status + a resultaat
+#    against a live OpenZaak:
+make verify-acl        # → "Cancelling a zaak records the geannuleerd status and a resultaat"
+#
+# 2. End-to-end: the domain check submits a registration, fires its 30-day timer early, and asserts
+#    the timeout worker both expires the registration (VERLOPEN) and cancels its zaak (Geannuleerd):
+make verify-domain     # → "the timed-out registration's zaak was cancelled to Geannuleerd in OpenZaak"
+```
+
+**The path:** Flowable P30D timer → `RegistratieVerlopen` job → domain `ExpireRegistrationWorker` → ACL
+`POST /annuleringen` → ZGW `resultaten` + `statussen` (Geannuleerd); the aggregate then moves to
+`Verlopen`. The ACL cancels the zaak **before** the aggregate is expired, so a failed ZGW call leaves the
+job for redelivery rather than diverging the two (ADR-0019).

docs/frontend-decisions.md

@@ -72,3 +72,98 @@ with the submit form (S-08c, #67); any deviation from NL DS will be recorded her
 - **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.
+
+## 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`.

docs/synthetic-data.md

@@ -14,6 +14,7 @@ All test users share the password **`test123`**.
 | Realm | Mimics | User | Identifying claim |
 |---|---|---|---|
 | `digid` | DigiD (burgers) | `jan-burger` | `bsn` = `123456782` |
+| `digid` | DigiD (burgers) | `sanne-burger` | `bsn` = `231477813` (S-26 resume e2e — its own user so it can leave an open registration) |
 | `eherkenning` | eHerkenning (bedrijven) | `acme-ondernemer` | `kvk` = `12345678` |
 | `eidas` | eIDAS (EU) | `pierre-dupont` | `eidas_id` = `FR/NL/AB-1234-5678` |
 | `medewerker` | Internal staff | `merel-behandelaar` | role `behandelaar` |

infra/docker-compose.local.yml

@@ -1,7 +1,12 @@
 # LOCAL development stack — runs with a plain `docker compose up`, no make / no
-# seed step / no bash. Use this on a local engine (Docker Desktop on Windows or
+# external seed step / no bash. Use this on a local engine (Docker Desktop on Windows or
 # macOS, or rootless Podman on Linux).
 #
+# Self-seeding (S-B04, #110, ADR-0020): unlike the CI stack — where the verify-* scripts seed the
+# zaaktype and register the NRC abonnement at test time — this stack does that itself, via one-shot
+# init containers (local-seed, nrc-subscribe) + a DMN deploy in flowable-init, so a fresh bring-up
+# completes the whole flow with no manual steps. `make verify-local` asserts it.
+#
 #   docker compose -f infra/docker-compose.local.yml up -d --build         # podman
 #   docker compose -f infra/docker-compose.local.yml up -d --build --wait  # Docker Desktop
 #   docker compose -f infra/docker-compose.local.yml down --volumes
@@ -17,7 +22,12 @@
 #
 # Port map (host):
 #   8000 OpenZaak · 8001 Open Notificaties · 8080 BFF · 8090 Flowable REST
-#   8100 ACL · 8180 Keycloak   (all admin: admin / admin — dev only)
+#   8100 ACL · 8130 Domain · 8180 Keycloak   (all admin: admin / admin — dev only)
+#   8140 self-service portal · 8141 openbaar register · 8142 behandel portal
+#
+# Portal OIDC on the HOST: browse the portals at their 8140/8141/8142 ports and log in via
+# Keycloak on localhost:8180 (KC_HOSTNAME below pins the issuer there; the BFF still validates
+# in-network via keycloak:8080). Test users are in docs/synthetic-data.md.
 
 services:
 
@@ -205,6 +215,12 @@ services:
       KEYCLOAK_ADMIN_PASSWORD: admin
       KC_HEALTH_ENABLED: "true"
       KC_HTTP_ENABLED: "true"
+      # Pin the frontend/issuer URL to the host-published address so a browser on the host and the
+      # tokens it gets both use localhost:8180. KC_HOSTNAME_BACKCHANNEL_DYNAMIC lets in-network
+      # callers (the BFF via keycloak:8080) still resolve token/jwks endpoints to their request host,
+      # so the BFF validates the localhost:8180 issuer while fetching keys over the compose network.
+      KC_HOSTNAME: http://localhost:8180
+      KC_HOSTNAME_BACKCHANNEL_DYNAMIC: "true"
     ports:
       - "8180:8080"
     volumes:
@@ -246,38 +262,79 @@ services:
     restart: "no"
     volumes:
       - ../workflows/registratie.bpmn:/work/registratie.bpmn:ro,z
+      - ../workflows/diploma-eligibility.dmn:/work/diploma-eligibility.dmn:ro,z
     command:
       - sh
       - -c
       - |
-        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        svc=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        dmn=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
+        until curl -sf -u rest-admin:test "$$svc" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        # Deploy the DMN to the DMN engine and the BPMN to the process engine as SEPARATE deployments:
+        # flowable-rest does NOT cascade a .dmn bundled in a process .bar into the DMN engine, so the DMN
+        # must go via dmn-api. The registratie process's DMN service task then resolves the decision across
+        # deployments by key (S-13, ADR-0016). Without this the WachtOpDocumenten completion 404s on the
+        # missing decision and the case never reaches Beoordelen (S-B04). Both steps are idempotent.
+        if curl -s -u rest-admin:test "$$dmn" | grep -q '"name":"diploma-eligibility.dmn"'; then
+          echo "diploma-eligibility DMN already deployed; skip"
         else
-          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+          curl -sf -u rest-admin:test -F 'file=@/work/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmn" >/dev/null && echo "deployed diploma-eligibility DMN"
+        fi
+        if curl -s -u rest-admin:test "$$svc?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie BPMN already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$svc" >/dev/null && echo "deployed registratie BPMN"
         fi
     depends_on:
       flowable-rest:
         condition: service_started
     networks: [cg]
 
+  # ── Local bootstrap: seed the zaaktype + wire the ACL (S-B04, #110, ADR-0020) ─────────────────
+  # The zaaktype UUID is assigned by OpenZaak at creation, so it can't be a static value in this
+  # file. This one-shot seeds + publishes the BIG zaaktype (and the Diploma informatieobjecttype)
+  # and writes their server-assigned URLs into a shared volume as acl.env, which the ACL sources on
+  # startup (below). It is the local-stack equivalent of what infra/run-domain-check.sh does for CI.
+  # Reaches OpenZaak by its container IP because a single-label host fails OpenZaak's URLValidator.
+  local-seed:
+    image: docker.io/library/python:3-slim
+    restart: "no"
+    volumes:
+      - ./openzaak/seed_catalogus.py:/work/seed_catalogus.py:ro,z
+      - ./local/seed-zaaktype.sh:/work/seed-zaaktype.sh:ro,z
+      - seed-env:/out
+    command: ["sh", "/work/seed-zaaktype.sh"]
+    depends_on:
+      openzaak:
+        condition: service_healthy
+    networks: [cg]
+
   # ── ACL ──────────────────────────────────────────────────────────────────
   acl:
     build:
       context: ../services/acl
       dockerfile: Dockerfile
     image: register-referentie/acl:dev
+    # The ACL discovers its zaaktype + informatieobjecttype URLs from the Catalogi API by the business
+    # keys below (S-27, ADR-0021), so no URL is injected. It still needs its OpenZaak BaseUrl pointed at
+    # a URL-valid host (OpenZaak rejects a single-label host like `openzaak` on zaak-create), so the
+    # local-seed one-shot writes that IP base into seed-env:/seed/acl.env, which the entrypoint sources
+    # (set -a) before the app starts. A runtime-generated env file is why we override the entrypoint here
+    # rather than use `env_file:` (which compose reads at parse time, before the seed has run).
+    entrypoint: ["/bin/sh", "-c", "set -a; . /seed/acl.env; set +a; exec dotnet Acl.Api.dll"]
     environment:
-      Acl__OpenZaak__BaseUrl: http://openzaak:8000/
+      Acl__OpenZaak__BaseUrl: http://openzaak:8000/   # placeholder; seed-env/acl.env supplies the IP base
       Acl__OpenZaak__ClientId: big-reference-seed
       Acl__OpenZaak__Secret: insecure-dev-secret-change-me
       Acl__Defaults__Bronorganisatie: "517439943"
       Acl__Defaults__VerantwoordelijkeOrganisatie: "517439943"
       Acl__Defaults__Vertrouwelijkheidaanduiding: openbaar
-      Acl__Defaults__ZaaktypeUrl: ${ACL_ZAAKTYPE_URL:-http://openzaak:8000/catalogi/api/v1/zaaktypen/00000000-0000-0000-0000-000000000000}
+      Acl__Defaults__ZaaktypeIdentificatie: BIG-REGISTRATIE
+      Acl__Defaults__InformatieobjecttypeOmschrijving: Diploma
     ports:
       - "8100:8080"
+    volumes:
+      - seed-env:/seed:ro
     healthcheck:
       test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
       interval: 5s
@@ -287,6 +344,8 @@ services:
     depends_on:
       openzaak:
         condition: service_healthy
+      local-seed:
+        condition: service_completed_successfully
     networks: [cg]
 
   # ── BFF ──────────────────────────────────────────────────────────────────
@@ -295,6 +354,14 @@ services:
       context: ../services/bff
       dockerfile: Dockerfile
     image: register-referentie/bff:dev
+    environment:
+      # Reach Keycloak over the compose network for metadata/keys; the discovered issuer is the
+      # host-pinned localhost:8180 (KC_HOSTNAME above), which is what browser tokens carry — so
+      # validation matches without the BFF ever needing to resolve localhost:8180 itself.
+      Keycloak__Authority: http://keycloak:8080/realms/digid
+      Keycloak__MedewerkerAuthority: http://keycloak:8080/realms/medewerker
+      Downstream__Domain__BaseUrl: http://domain:8080/
+      Downstream__Projection__BaseUrl: http://projection-api:8080/
     ports:
       - "8080:8080"
     healthcheck:
@@ -303,6 +370,39 @@ services:
       timeout: 3s
       retries: 5
       start_period: 10s
+    depends_on:
+      domain:
+        condition: service_healthy
+      projection-api:
+        condition: service_healthy
+      keycloak:
+        condition: service_started
+    networks: [cg]
+
+  # ── BIG Domain Service (S-05) ─────────────────────────────────────────────
+  domain:
+    build:
+      context: ../services/domain
+      dockerfile: Dockerfile
+    image: register-referentie/domain:dev
+    environment:
+      Flowable__BaseUrl: http://flowable-rest:8080/flowable-rest/
+      Flowable__Username: rest-admin
+      Flowable__Password: test
+      Acl__BaseUrl: http://acl:8080/
+    ports:
+      - "8130:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      acl:
+        condition: service_healthy
+      flowable-init:
+        condition: service_completed_successfully
     networks: [cg]
 
   # ── Read projection (S-06) ────────────────────────────────────────────────
@@ -328,6 +428,10 @@ services:
     image: register-referentie/event-subscriber:dev
     environment:
       ConnectionStrings__Projection: Host=projection-db;Database=projection;Username=projection;Password=projection
+      # The subscriber enriches the projection with each zaak's reference by asking the ACL — the only
+      # code allowed to read ZGW (§8.1, #78). Required: startup throws without it (parity with the
+      # canonical compose).
+      Acl__BaseUrl: http://acl:8080/
       EventSubscriber__Webhook__AuthToken: ${NOTIFICATION_WEBHOOK_TOKEN:-Bearer big-reference-notifications}
     ports:
       - "8110:8080"
@@ -340,6 +444,33 @@ services:
     depends_on:
       projection-db:
         condition: service_healthy
+      acl:
+        condition: service_healthy
+    networks: [cg]
+
+  # ── Local bootstrap: register the NRC abonnement (S-B04, #110, ADR-0020) ──────────────────────
+  # Without a subscription, OpenZaak's notifications reach NRC and are delivered nowhere, so the
+  # projection (and the openbaar register) stay empty. This one-shot registers an abonnement on the
+  # `zaken` kanaal pointing at the event-subscriber's /notifications callback — the CI equivalent is
+  # infra/verify-notification-driver.py. The callback uses the event-subscriber's container IP (a
+  # single-label host fails NRC's URLValidator). It is a leaf (nothing depends on it), so it can wait
+  # for the event-subscriber without creating a cycle with the ACL bootstrap.
+  nrc-subscribe:
+    image: docker.io/library/python:3-slim
+    restart: "no"
+    volumes:
+      - ./local/register-abonnement.py:/work/register-abonnement.py:ro,z
+    environment:
+      NRC_BASE: http://nrc-web:8000
+      SINK_HOST: event-subscriber
+      SINK_PORT: "8080"
+      SINK_AUTH: ${NOTIFICATION_WEBHOOK_TOKEN:-Bearer big-reference-notifications}
+    command: ["python", "/work/register-abonnement.py"]
+    depends_on:
+      nrc-web:
+        condition: service_healthy
+      event-subscriber:
+        condition: service_started
     networks: [cg]
 
   projection-api:
@@ -362,11 +493,80 @@ services:
         condition: service_healthy
     networks: [cg]
 
+  # ── Portals (S-08/S-09/S-12) ──────────────────────────────────────────────
+  # nginx serves each Angular app and reverse-proxies its endpoint group to the BFF (same-origin).
+  # The images bake config.json with the compose authority (keycloak:8080), which a HOST browser
+  # can't resolve — so here we bind-mount a config.json pointing at the host-published localhost:8180
+  # (matching KC_HOSTNAME). openbaar is anonymous and needs no config.
+  self-service:
+    build:
+      context: ..
+      dockerfile: apps/self-service/Dockerfile
+    image: register-referentie/self-service:dev
+    ports:
+      - "8140:80"
+    volumes:
+      - ./local-config/self-service.config.json:/usr/share/nginx/html/config.json:ro,z
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+      keycloak:
+        condition: service_started
+    networks: [cg]
+
+  openbaar:
+    build:
+      context: ..
+      dockerfile: apps/openbaar/Dockerfile
+    image: register-referentie/openbaar:dev
+    ports:
+      - "8141:80"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+    networks: [cg]
+
+  behandel:
+    build:
+      context: ..
+      dockerfile: apps/behandel/Dockerfile
+    image: register-referentie/behandel:dev
+    ports:
+      - "8142:80"
+    volumes:
+      - ./local-config/behandel.config.json:/usr/share/nginx/html/config.json:ro,z
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+      keycloak:
+        condition: service_started
+    networks: [cg]
+
 volumes:
   oz-db:
   nrc-db:
   flowable-db:
   projection-db:
+  # Carries the seed-generated acl.env (server-assigned zaaktype URLs) from local-seed to the ACL.
+  seed-env:
 
 networks:
   cg:

infra/docker-compose.yml

@@ -15,12 +15,12 @@
 #
 #   docker compose -f infra/docker-compose.yml up -d --build --wait
 #
-# After first boot, seed the BIG catalogus and note the zaaktype URL:
-#   python infra/openzaak/seed_catalogus.py
-# Then set ACL_ZAAKTYPE_URL in a .env file or your shell and re-up the acl
-# service:
-#   export ACL_ZAAKTYPE_URL=http://openzaak:8000/catalogi/api/v1/zaaktypen/<uuid>
-#   docker compose -f infra/docker-compose.yml up -d acl
+# After first boot, seed + publish the BIG catalogus:
+#   OZ_PUBLISH=1 python infra/openzaak/seed_catalogus.py
+# The ACL discovers the zaaktype by identificatie (S-27, ADR-0021), so there is no URL to inject —
+# just point its BaseUrl at an OpenZaak host OpenZaak accepts on zaak-create (a container IP; a
+# single-label host is rejected):
+#   ACL_OPENZAAK_BASEURL=http://<openzaak-ip>:8000/ docker compose -f infra/docker-compose.yml up -d acl
 
 services:
 
@@ -259,19 +259,30 @@ services:
   flowable-init:
     image: docker.io/curlimages/curl:latest
     restart: "no"
-    # registratie.bpmn is streamed into this external volume by infra/seed-config.sh.
+    # registratie.bpmn + diploma-eligibility.dmn are streamed into this external volume by
+    # infra/seed-config.sh.
     volumes:
       - fl-bpmn:/work:ro
     command:
       - sh
       - -c
       - |
-        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        svc=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        dmn=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
+        until curl -sf -u rest-admin:test "$$svc" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        # Deploy the DMN to the DMN engine and the BPMN to the process engine as SEPARATE deployments:
+        # flowable-rest does NOT cascade a .dmn bundled in a process .bar into the DMN engine, so the DMN
+        # must go via dmn-api. The process's DMN service task then resolves the decision across deployments
+        # by key (S-13, ADR-0016). Both steps are idempotent (skip if already deployed).
+        if curl -s -u rest-admin:test "$$dmn" | grep -q '"name":"diploma-eligibility.dmn"'; then
+          echo "diploma-eligibility DMN already deployed; skip"
         else
-          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+          curl -sf -u rest-admin:test -F 'file=@/work/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmn" >/dev/null && echo "deployed diploma-eligibility DMN"
+        fi
+        if curl -s -u rest-admin:test "$$svc?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie BPMN already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$svc" >/dev/null && echo "deployed registratie BPMN"
         fi
     depends_on:
       flowable-rest:
@@ -285,6 +296,10 @@ services:
       dockerfile: Dockerfile
     image: register-referentie/acl:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: acl
       # Overridable so verify-domain can point the ACL at the same OpenZaak host that
       # owns the seeded zaaktype URL (host-consistent zaak creation, ADR-0009).
       Acl__OpenZaak__BaseUrl: ${ACL_OPENZAAK_BASEURL:-http://openzaak:8000/}
@@ -293,8 +308,12 @@ services:
       Acl__Defaults__Bronorganisatie: "517439943"
       Acl__Defaults__VerantwoordelijkeOrganisatie: "517439943"
       Acl__Defaults__Vertrouwelijkheidaanduiding: openbaar
-      # Override with the real zaaktype URL after running seed_catalogus.py.
-      Acl__Defaults__ZaaktypeUrl: ${ACL_ZAAKTYPE_URL:-http://openzaak:8000/catalogi/api/v1/zaaktypen/00000000-0000-0000-0000-000000000000}
+      # The ACL resolves the (server-assigned) zaaktype + diploma informatieobjecttype URLs from the
+      # Catalogi API by these stable business keys (S-27, ADR-0021) — no URL to capture and inject.
+      # BaseUrl above stays overridable because OpenZaak rejects a single-label host on zaak creation,
+      # so verify-domain still points the ACL at OpenZaak's container IP.
+      Acl__Defaults__ZaaktypeIdentificatie: BIG-REGISTRATIE
+      Acl__Defaults__InformatieobjecttypeOmschrijving: Diploma
     ports:
       - "8100:8080"
     healthcheck:
@@ -319,6 +338,10 @@ services:
       dockerfile: Dockerfile
     image: register-referentie/domain:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: domain
       Flowable__BaseUrl: http://flowable-rest:8080/flowable-rest/
       Flowable__Username: rest-admin
       Flowable__Password: test
@@ -345,12 +368,20 @@ services:
       dockerfile: Dockerfile
     image: register-referentie/bff:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: bff
       # The BFF is the portals' only backend; it validates digid tokens and fans out (ADR-0010).
       # Keycloak (start-dev) derives the issuer from the request host, so the BFF authority and the
       # verify token request both use keycloak:8080 to keep the issuer consistent.
       Keycloak__Authority: http://keycloak:8080/realms/digid
+      # Behandelaars authenticate against the medewerker realm; the BFF validates it for /behandel/* (S-12c).
+      Keycloak__MedewerkerAuthority: http://keycloak:8080/realms/medewerker
       Downstream__Domain__BaseUrl: http://domain:8080/
       Downstream__Projection__BaseUrl: http://projection-api:8080/
+      # The beheer catalogus read reaches the ACL directly (S-15a, ADR-0025).
+      Downstream__Acl__BaseUrl: http://acl:8080/
     ports:
       - "8080:8080"
     healthcheck:
@@ -395,7 +426,14 @@ services:
       dockerfile: services/event-subscriber/Dockerfile
     image: register-referentie/event-subscriber:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: event-subscriber
       ConnectionStrings__Projection: Host=projection-db;Database=projection;Username=projection;Password=projection
+      # The subscriber enriches the projection with each zaak's reference (identificatie) by asking
+      # the ACL — the only code allowed to read ZGW (§8.1, #78).
+      Acl__BaseUrl: http://acl:8080/
       # The bearer Open Notificaties must present on the abonnement callback. NRC's
       # registration probe expects a 401 without it (ADR-0007). Dev-only token.
       EventSubscriber__Webhook__AuthToken: ${NOTIFICATION_WEBHOOK_TOKEN:-Bearer big-reference-notifications}
@@ -410,6 +448,8 @@ services:
     depends_on:
       projection-db:
         condition: service_healthy
+      acl:
+        condition: service_healthy
     networks: [cg]
 
   # The read side of the projection. Shares Projection.ReadModel, so build context is root.
@@ -419,6 +459,10 @@ services:
       dockerfile: services/projection-api/Dockerfile
     image: register-referentie/projection-api:dev
     environment:
+      # OpenTelemetry traces → Tempo (S-16b, ADR-0023).
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+      OTEL_EXPORTER_OTLP_PROTOCOL: grpc
+      OTEL_SERVICE_NAME: projection-api
       ConnectionStrings__Projection: Host=projection-db;Database=projection;Username=projection;Password=projection
     ports:
       - "8120:8080"
@@ -433,6 +477,142 @@ services:
         condition: service_healthy
     networks: [cg]
 
+  # ── Self-Service portal (S-08d) ────────────────────────────────────────────
+  # nginx serves the Angular app and reverse-proxies /self-service + /openbaar to the BFF
+  # (same-origin, no CORS). The Playwright e2e drives it inside this network so the DigiD
+  # token issuer (keycloak:8080) matches the BFF's authority (ADR-0010).
+  self-service:
+    build:
+      context: ..
+      dockerfile: apps/self-service/Dockerfile
+    image: register-referentie/self-service:dev
+    ports:
+      - "8140:80"
+    healthcheck:
+      # 127.0.0.1, not localhost: nginx listens on IPv4 only, but localhost resolves to ::1 first.
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+      keycloak:
+        condition: service_started
+    networks: [cg]
+
+  # The openbaar (public) register portal: nginx serves the Angular app and reverse-proxies
+  # /openbaar to the BFF. Anonymous — no DigiD, no Keycloak dependency (S-09).
+  openbaar:
+    build:
+      context: ..
+      dockerfile: apps/openbaar/Dockerfile
+    image: register-referentie/openbaar:dev
+    ports:
+      - "8141:80"
+    healthcheck:
+      # 127.0.0.1, not localhost: nginx listens on IPv4 only, but localhost resolves to ::1 first.
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+    networks: [cg]
+
+  # The behandel portal: nginx serves the Angular app and reverse-proxies /behandel to the BFF.
+  # Behandelaars log in against the Keycloak medewerker realm (ADR-0013; S-12).
+  behandel:
+    build:
+      context: ..
+      dockerfile: apps/behandel/Dockerfile
+    image: register-referentie/behandel:dev
+    ports:
+      - "8142:80"
+    healthcheck:
+      # 127.0.0.1, not localhost: nginx listens on IPv4 only, but localhost resolves to ::1 first.
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+      keycloak:
+        condition: service_started
+    networks: [cg]
+
+  # The beheer portal: nginx serves the Angular app and reverse-proxies /beheer to the BFF.
+  # Beheerders log in against the Keycloak medewerker realm (same realm as behandel, S-15a).
+  beheer:
+    build:
+      context: ..
+      dockerfile: apps/beheer/Dockerfile
+    image: register-referentie/beheer:dev
+    ports:
+      - "8143:80"
+    healthcheck:
+      # 127.0.0.1, not localhost: nginx listens on IPv4 only, but localhost resolves to ::1 first.
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+      keycloak:
+        condition: service_started
+    networks: [cg]
+
+  # ── Observability backplane (S-16a, ADR-0023) ──────────────────────────────
+  # Grafana-native stack: Tempo ingests OTLP traces (the .NET services export
+  # straight to it — no collector hop, S-16b), Prometheus scrapes service
+  # /metrics (S-16c), and Grafana reads both with datasources auto-provisioned.
+  # Config is baked into small built images (COPY) rather than streamed into
+  # external config volumes like the upstream CG modules — these aren't verbatim
+  # peer images, so a built image is the simpler path that still reaches sibling
+  # containers on the CI runner. Not in WAIT_SVCS: run-observability-check.sh
+  # polls Grafana itself, so no in-image healthcheck tool is needed.
+  tempo:
+    build:
+      context: ./observability/tempo
+    image: register-referentie/tempo:dev
+    command: ["-config.file=/etc/tempo.yaml"]
+    # Cap the backplane's footprint so it can't starve the app stack + the Playwright browser on the
+    # memory-tight CI runner (verify-e2e OOM history, commit d5e5fa2). Generous vs idle (~150M).
+    mem_limit: 400m
+    networks: [cg]
+
+  prometheus:
+    build:
+      context: ./observability/prometheus
+    image: register-referentie/prometheus:dev
+    mem_limit: 400m
+    ports:
+      - "9090:9090"
+    networks: [cg]
+
+  grafana:
+    build:
+      context: ./observability/grafana
+    image: register-referentie/grafana:dev
+    mem_limit: 512m
+    environment:
+      GF_SECURITY_ADMIN_USER: admin
+      GF_SECURITY_ADMIN_PASSWORD: admin
+      GF_AUTH_ANONYMOUS_ENABLED: "true"
+    ports:
+      - "3000:3000"
+    depends_on:
+      - tempo
+      - prometheus
+    networks: [cg]
+
 volumes:
   oz-db:
   nrc-db:

infra/flowable/docker-compose.yml

@@ -35,24 +35,35 @@ services:
         condition: service_healthy
     networks: [cg]
 
-  # Deploys workflows/registratie.bpmn via the REST API once flowable-rest is up.
-  # Idempotent: skips if a deployment named "registratie" already exists.
+  # Deploys registratie.bpmn (process engine) and diploma-eligibility.dmn (DMN engine) via the REST
+  # API once flowable-rest is up. Idempotent: skips each if already deployed.
   flowable-init:
     image: docker.io/curlimages/curl:latest
     restart: "no"
-    # registratie.bpmn is streamed into this external volume by infra/seed-config.sh.
+    # registratie.bpmn + diploma-eligibility.dmn are streamed into this external volume by
+    # infra/seed-config.sh.
     volumes:
       - fl-bpmn:/work:ro
     command:
       - sh
       - -c
       - |
-        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
-        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
-        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
-          echo "registratie already deployed; skip"
+        svc=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        dmn=http://flowable-rest:8080/flowable-rest/dmn-api/dmn-repository/deployments
+        until curl -sf -u rest-admin:test "$$svc" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        # Deploy the DMN to the DMN engine and the BPMN to the process engine as SEPARATE deployments:
+        # flowable-rest does NOT cascade a .dmn bundled in a process .bar into the DMN engine, so the DMN
+        # must go via dmn-api. The process's DMN service task then resolves the decision across deployments
+        # by key (S-13, ADR-0016). Both steps are idempotent (skip if already deployed).
+        if curl -s -u rest-admin:test "$$dmn" | grep -q '"name":"diploma-eligibility.dmn"'; then
+          echo "diploma-eligibility DMN already deployed; skip"
         else
-          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+          curl -sf -u rest-admin:test -F 'file=@/work/diploma-eligibility.dmn;filename=diploma-eligibility.dmn' "$$dmn" >/dev/null && echo "deployed diploma-eligibility DMN"
+        fi
+        if curl -s -u rest-admin:test "$$svc?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie BPMN already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$svc" >/dev/null && echo "deployed registratie BPMN"
         fi
     depends_on:
       flowable-rest: