register-referentie/docs/demo-script.md

# Demo script

A running log of demoable outcomes, one section per slice. Each entry is a short,
copy-pasteable walkthrough against a local `make up` stack.

---

## 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
self-service portal (NL Design System styling); the page confirms with the reference returned by the
BFF. The bsn comes from the DigiD token, so it's a confirm-and-submit flow (no bsn field).

```bash
# 1. Bring the backend + Keycloak up (BFF on :8080, Keycloak on :8180).
make up

# 2. Serve the portal (dev server); it redirects to Keycloak for DigiD login.
pnpm nx serve self-service        # → http://localhost:4200

# 3. In the browser: log in as the mock DigiD user jan-burger / test123, then submit.
#    The page shows the returned registration reference.
```

> First real UI. The full **login → submit → success** happy path is automated in **S-08d**
> (Playwright, against the compose-served app). Component tests + an axe WCAG 2.1 AA check on the
> submit page run headless in the `frontend` CI lane. See `docs/frontend-decisions.md`.

---

## S-08a — Nx workspace + self-service portal skeleton

**Outcome:** the frontend foundation — an Nx (pnpm) monorepo with the `self-service` Angular app
(standalone + signals), lint/test/build green in a CI Node lane. The login + submit form follow in
S-08c.

```bash
# From a fresh clone (Node 24 + pnpm 11):
pnpm install                       # native builds are pre-approved in pnpm-workspace.yaml
pnpm nx test self-service          # Vitest component test
pnpm nx build self-service         # production build
pnpm nx serve self-service         # → http://localhost:4200  (placeholder page)
# Or the CI-equivalent one-shot:
make frontend                      # install + nx lint/test/build
```

> Nx manages only `apps/`+`libs/`; the .NET services stay on `dotnet`/the Makefile. NL Design System
> and the real form arrive in S-08c (#67); see `docs/frontend-decisions.md`.

---

## S-07 — BFF: the portals' single backend

**Outcome:** the BFF validates Keycloak `digid` tokens on the self-service submit (forwarding the
bsn to the domain) and serves the openbaar register anonymously with only public-safe fields — the
front door the portals (S-08/S-09) will talk to.

**The path:** portal → BFF `POST /self-service/registrations` (token-gated) → domain; and
BFF `GET /openbaar/register` (anonymous) → projection-api. See ADR-0010.

```bash
# 1. Bring the full stack up.
make up

# 2. Drive the BFF end-to-end (401 without a token, 202 with a real digid token, anonymous openbaar).
make verify-bff        # → "OK — BFF: 401 without token, 202 with a digid token, anonymous ..."

# 3. Try it by hand (BFF on host port 8080).
#    a) A digid access token for the mock user jan-burger (bsn 123456782):
tok=$(curl -s -X POST http://localhost:8180/realms/digid/protocol/openid-connect/token \
  -d grant_type=password -d client_id=big-portal -d username=jan-burger -d password=test123 \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

#    b) Submit — without the token it is 401; with it, 202:
curl -s -o /dev/null -w "no token  -> %{http_code}\n" -X POST http://localhost:8080/self-service/registrations
curl -s -o /dev/null -w "with token-> %{http_code}\n" -X POST http://localhost:8080/self-service/registrations \
  -H "Authorization: Bearer $tok"

#    c) The openbaar register is anonymous and exposes only id + status (never the bsn):
curl -fsS http://localhost:8080/openbaar/register | jq
```

> The self-service token is validated against Keycloak's `digid` realm; the openbaar lookup needs no
> token (S-09). The generated contract lives at `services/bff/openapi.json` — S-08's client is built
> from it.

---

## S-05 — BIG Domain Service: submit a registration

**Outcome:** submitting a registration starts a Flowable process; the external-task worker
opens a zaak via the ACL and records it on the aggregate — the upstream half of the skeleton
that produces the zaak S-06 then projects.

**The path:** domain `POST /registrations` → Flowable `registratie` process → `OpenZaakAanmaken`
worker → ACL → OpenZaak; `GET /registrations/{id}` shows the opened zaak (ADR-0009).

```bash
# 1. Bring the full stack up (seeds config, builds our services, waits for health).
make up

# 2. Drive the full path end-to-end. This also seeds a published BIG zaaktype and points the
#    ACL at it (the zaak's zaaktype URL is server-assigned, so it isn't known at bring-up).
make verify-domain      # → "OK — the domain opened a zaak and recorded it on the registration"

# 3. Submit one yourself (domain on host port 8130). Returns 202 + a Location to read back.
loc=$(curl -fsS -D - -o /dev/null -X POST http://localhost:8130/registrations \
  -H 'Content-Type: application/json' -d '{"bsn":"123456782"}' | sed -n 's/\r$//; s/^[Ll]ocation: //p')

# 4. The worker opens the zaak off the request path (eventual consistency, ADR-0009); poll
#    until zaakUrl is filled. (Step 2 must have run first, so the ACL knows the zaaktype.)
curl -fsS "http://localhost:8130$loc" | jq
# → { "registrationId": "...", "status": "Ingediend", "zaakUrl": "http://.../zaken/api/v1/zaken/<uuid>" }
```

> Registration state is in-memory for this slice (ADR-0009); the rebuildable read model is the
> projection (S-06), fed by the very zaak this flow opens.

---

## S-06 — Event Subscriber + read projection

**Outcome:** a zaak created in OpenZaak flows through NRC to the Event Subscriber, which
projects it into a rebuildable read projection the projection-api serves.

**The path:** OpenZaak → (notification) NRC → (abonnement callback) Event Subscriber →
`register_projection` → projection-api `GET /register`.

```bash
# 1. Bring the full stack up (seeds config, builds our services, waits for health).
make up

# 2. Register the Event Subscriber's abonnement and create a zaak, then read it back.
#    (The verify-projection check does exactly this end-to-end and asserts the result.)
make verify-projection            # → "OK — projection-api serves zaak <uuid> with status INGEDIEND"

# 3. Observe the projection directly via the read API (host port 8120).
curl -fsS http://localhost:8120/register | jq
# → [ { "id": "<zaak-uuid>", "status": "INGEDIEND", "bsn": null, "naamPlaceholder": null } ]

# 4. Idempotency + rebuild: replays don't duplicate; a rebuild repopulates from the
#    notification log (no OpenZaak access needed — ADR-0008).
curl -fsS -X POST http://localhost:8110/admin/rebuild   # Event Subscriber, host port 8110
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.