feat(workflow): Flowable + registratie.bpmn external task (closes #4) (#44)

.gitignore

@@ -22,6 +22,10 @@ node_modules/
 dist/
 .angular/
 
+# Python / MkDocs
+.venv/
+site/
+
 # OS
 .DS_Store
 Thumbs.db

Makefile

@@ -8,6 +8,15 @@
 SLN        := services/bff/Bff.slnx
 COMPOSE    := infra/docker-compose.yml
 HEALTH_URL := http://localhost:8080/health
+OZ_COMPOSE  := infra/openzaak/docker-compose.yml
+OZ_BASE     := http://localhost:8000
+NRC_COMPOSE := infra/opennotificaties/docker-compose.yml
+NRC_BASE    := http://localhost:8001
+KC_COMPOSE  := infra/keycloak/docker-compose.yml
+KC_BASE     := http://localhost:8180
+FL_COMPOSE  := infra/flowable/docker-compose.yml
+FL_BASE     := http://localhost:8090/flowable-rest/service
+STACK_FILES := -f $(OZ_COMPOSE) -f $(NRC_COMPOSE)
 
 # On a rootless Podman dev box, point Docker CLI/Compose at the Podman socket —
 # but only if that socket exists and DOCKER_HOST isn't already set, so real
@@ -19,7 +28,7 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif
 
-.PHONY: ci lint build unit smoke down changelog help
+.PHONY: ci lint build unit smoke 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, smoke (mirrors Gitea Actions)
 ci: lint build unit smoke
@@ -49,6 +58,89 @@ down:
 changelog:
 	git-cliff --output CHANGELOG.md
 
+## openzaak-up: start the OpenZaak stack (migrations run on first start)
+openzaak-up:
+	docker compose -f $(OZ_COMPOSE) up -d
+
+## openzaak-smoke: start OpenZaak, then assert it is up with auth enforced
+openzaak-smoke:
+	docker compose -f $(OZ_COMPOSE) up -d
+	@bash -c 'set -e; \
+	  echo "waiting for OpenZaak to respond..."; \
+	  for i in $$(seq 1 60); do \
+	    code=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/zaken || true); \
+	    [ -n "$$code" ] && [ "$$code" != "000" ] && break; sleep 3; \
+	  done; \
+	  echo "GET /zaken/api/v1/zaken (unauth) -> $$code (expect 403, auth enforced)"; test "$$code" = "403"; \
+	  admin=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/admin/); \
+	  echo "GET /admin/             -> $$admin (expect 302)"; test "$$admin" = "302"; \
+	  root=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/); \
+	  echo "GET /zaken/api/v1/      -> $$root (expect 200)"; test "$$root" = "200"; \
+	  echo "OpenZaak smoke OK"'
+
+## openzaak-seed: bring OpenZaak up and seed the BIG catalogus (idempotent)
+openzaak-seed: openzaak-up
+	@bash -c 'for i in $$(seq 1 50); do \
+	    c=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/catalogi/api/v1/ || true); \
+	    [ "$$c" = "200" ] && break; sleep 3; done; echo "OpenZaak ready ($$c)"'
+	python3 infra/openzaak/seed_catalogus.py
+
+## openzaak-down: stop and remove the OpenZaak stack (wipes data)
+openzaak-down:
+	docker compose -f $(OZ_COMPOSE) down --volumes
+
+## stack-up: start OpenZaak + Open Notificaties together (shared network)
+stack-up:
+	docker compose $(STACK_FILES) up -d
+
+## stack-smoke: start both, assert OpenZaak (403/302/200) and NRC (302) are reachable
+stack-smoke: stack-up
+	@bash -c 'set -e; \
+	  echo "waiting for OpenZaak + Open Notificaties..."; \
+	  for i in $$(seq 1 60); do \
+	    oz=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/admin/ || true); \
+	    nrc=$$(curl -s -o /dev/null -w "%{http_code}" $(NRC_BASE)/admin/ || true); \
+	    [ "$$oz" = "302" ] && [ "$$nrc" = "302" ] && break; sleep 3; done; \
+	  z=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/zaken); \
+	  echo "OpenZaak /zaken (unauth) -> $$z (expect 403)"; test "$$z" = "403"; \
+	  echo "OpenZaak /admin/         -> $$oz (expect 302)"; test "$$oz" = "302"; \
+	  echo "Open Notificaties /admin/-> $$nrc (expect 302)"; test "$$nrc" = "302"; \
+	  echo "stack smoke OK"'
+
+## stack-down: stop and remove both stacks (wipes data)
+stack-down:
+	docker compose $(STACK_FILES) down --volumes
+
+## keycloak-up: start Keycloak with the four imported realms
+keycloak-up:
+	docker compose -f $(KC_COMPOSE) up -d
+
+## keycloak-smoke: start Keycloak, then verify each realm logs in + returns its claim
+keycloak-smoke: keycloak-up
+	@bash -c 'for i in $$(seq 1 60); do \
+	    c=$$(curl -s -o /dev/null -w "%{http_code}" $(KC_BASE)/realms/digid/.well-known/openid-configuration || true); \
+	    [ "$$c" = "200" ] && break; sleep 3; done; echo "Keycloak ready ($$c)"'
+	python3 infra/keycloak/check_realms.py
+
+## keycloak-down: stop and remove Keycloak
+keycloak-down:
+	docker compose -f $(KC_COMPOSE) down --volumes
+
+## flowable-up: start Flowable (deploys registratie.bpmn on boot)
+flowable-up:
+	docker compose -f $(FL_COMPOSE) up -d
+
+## flowable-smoke: start Flowable, then verify a started instance waits on the external task
+flowable-smoke: flowable-up
+	@bash -c 'for i in $$(seq 1 80); do \
+	    c=$$(curl -s -o /dev/null -w "%{http_code}" -u rest-admin:test $(FL_BASE)/repository/process-definitions?key=registratie || true); \
+	    [ "$$c" = "200" ] && break; sleep 3; done; echo "Flowable ready ($$c)"'
+	python3 infra/flowable/verify.py
+
+## flowable-down: stop and remove Flowable
+flowable-down:
+	docker compose -f $(FL_COMPOSE) down --volumes
+
 ## help: list available targets
 help:
 	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/^## //'

README.md

@@ -41,31 +41,32 @@ For the architecture rationale, see [docs/PRD.md §3](docs/PRD.md) and [docs/arc
 
 **Prerequisites**
 
-- Docker Engine (or Docker Desktop) with Compose v2
-- ~8 GB free RAM, ~10 GB free disk
-- Bash or PowerShell
+- .NET 10 SDK (for `make lint/build/unit`)
+- A container engine with Compose v2 — Docker, or rootless Podman (see [docs/runbooks/ci.md](docs/runbooks/ci.md) for the Podman + Compose-provider setup)
+- `make`, `curl`, `git`
+- ~4 GB free RAM, ~5 GB free disk (grows as services land)
 
-**Bring the stack up**
+**Clone**
 
 ```bash
-git clone https://gitea.respellion.local/respellion/register-reference.git
-cd register-reference
-cp .env.example .env          # edit if you change ports
-docker compose -f infra/docker-compose.yml up -d
+git clone git@git.labs.respellion.tech:eho/register-referentie.git
+cd register-referentie
 ```
 
-Health checks should be green within ~3 minutes on a developer machine. If something fails, see [docs/runbooks/local-startup.md](docs/runbooks/local-startup.md).
+**Wired today (Iteration 0):** only the placeholder BFF exists so far. Get to green in under 10 minutes — run the full check gate, or just the running service:
 
-> **Wired today (Iteration 0):** only the placeholder BFF is in `infra/docker-compose.yml` so far. Bring it up and smoke-test its health endpoint:
->
-> ```bash
-> docker compose -f infra/docker-compose.yml up -d --build --wait
-> curl http://localhost:8080/health   # -> Healthy
-> ```
->
-> `--wait` exits non-zero unless the container reports healthy, so this doubles as the compose-up smoke test. The remaining services and the URLs below land in later slices.
+```bash
+make ci          # lint + build + unit + container smoke — the CI gate
+```
 
-**Default URLs**
+```bash
+docker compose -f infra/docker-compose.yml up -d --build --wait
+curl http://localhost:8080/health     # -> Healthy
+```
+
+`--wait` exits non-zero unless the container reports healthy, so it doubles as the compose-up smoke test. The remaining services and the URLs below land in later slices.
+
+**Target service URLs** *(most land in later slices)*
 
 | Service | URL |
 |---|---|
@@ -73,7 +74,7 @@ Health checks should be green within ~3 minutes on a developer machine. If somet
 | Openbaar register | http://localhost:4201 |
 | Behandel-portal | http://localhost:4202 |
 | Beheer-portal | http://localhost:4203 |
-| BFF | http://localhost:5000 |
+| BFF | http://localhost:8080 |
 | OpenZaak | http://localhost:8000 |
 | Open Notificaties | http://localhost:8001 |
 | Flowable | http://localhost:8080 |
@@ -82,10 +83,12 @@ Health checks should be green within ~3 minutes on a developer machine. If somet
 
 Test credentials, BSNs, and personas: see [docs/synthetic-data.md](docs/synthetic-data.md).
 
-**Re-seed synthetic data**
+**Build the docs site**
 
 ```bash
-./tools/seed.sh               # or pwsh ./tools/seed.ps1
+python3 -m venv .venv && .venv/bin/pip install mkdocs-material
+.venv/bin/mkdocs serve         # live preview at http://localhost:8000
+.venv/bin/mkdocs build         # static site in ./site
 ```
 
 ---

docs/architecture/adr-0001-loose-coupling.md

@@ -0,0 +1,58 @@
+# ADR-0001: Loose coupling to upstream Common Ground modules
+
+- **Status:** Accepted
+- **Date:** 2026-06-03
+- **Deciders:** Respellion engineering
+- **Template note:** This is the first ADR and doubles as the worked example of
+  the Nygard template. Copy its shape for new ADRs (`adr-NNNN-title.md`).
+
+## Context
+
+This reference application orchestrates several upstream Common Ground modules —
+OpenZaak (ZGW APIs), Open Notificaties (NRC), Objecten/Objecttypen, Flowable,
+Keycloak. Each is an independently developed, independently deployed peer. The
+temptation in a demo is to reach straight into a peer's database or couple to its
+internal schema to move faster. That coupling is exactly what makes Common Ground
+landscapes brittle and un-upgradeable in practice.
+
+We need a stance, recorded up front, on how our services may talk to these peers.
+
+## Decision
+
+**We integrate with upstream modules only through their documented public APIs, and
+we isolate that integration behind explicit anti-corruption boundaries.**
+
+Concretely (mirrors CLAUDE.md §8):
+
+1. The **ACL** is the only code that talks to ZGW APIs; no other service constructs
+   ZGW URLs.
+2. The **Workflow Client** is the only code that talks to Flowable; BPMN models hold
+   no OpenZaak knowledge.
+3. **Portals talk only to the BFF** — never directly to a backend or a peer module.
+4. **No direct database access across services or to any peer.** Each service owns
+   its schema; the Read Projection is a rebuildable derived artefact.
+5. **Idempotency at every event boundary** (the Event Subscriber tolerates duplicate
+   and out-of-order NRC events).
+
+Bending any of these is an ADR-worthy moment (CLAUDE.md §14): stop and open an
+`adr-proposal` issue first.
+
+## Consequences
+
+**Positive**
+
+- Upstream modules can be upgraded or swapped behind their APIs without rippling
+  through our services.
+- Coupling is visible and minimal — anti-corruption code lives in one named place.
+- The architecture teaches the Common Ground pattern by enforcing it.
+
+**Negative / costs**
+
+- More indirection: a translation layer (ACL, Workflow Client) instead of direct
+  calls. Accepted — it's the point.
+- Eventual consistency across aggregates must be designed for, not assumed away.
+
+**Follow-up**
+
+- Each integration slice that touches a boundary references this ADR; new boundary
+  decisions get their own ADR.

docs/architecture/adr-0002-catalogus-design.md

@@ -0,0 +1,53 @@
+# ADR-0002: BIG catalogus design and OpenZaak seeding
+
+- **Status:** Accepted
+- **Date:** 2026-06-03
+- **Deciders:** Respellion engineering
+- **Relates to:** S-01 (#2)
+
+## Context
+
+S-01 needs a reproducible `BIG` catalogus in OpenZaak with a **lean** `BIG-registratie`
+zaaktype (only schema-mandatory fields) plus a `bsn` eigenschap, and a JWT client that
+can list zaaktypen. We had to decide *how* to provision this idempotently at startup.
+
+Findings from the OpenZaak image (`openzaak/open-zaak:latest`):
+- `setup_configuration` (run by the init container) is declarative and idempotent, with
+  steps for **JWT secrets** and **applicaties** (`vng_api_common_credentials`,
+  `vng_api_common_applicaties`) — but **no step for catalogi/zaaktypen**.
+- Catalogus/zaaktype/eigenschap can only be created through the **ZTC REST API**.
+- Publishing a zaaktype requires ≥1 roltype, ≥1 resultaattype and ≥2 statustypen.
+
+## Decision
+
+1. **Provision the JWT client declaratively** via `infra/openzaak/setup_configuration/data.yaml`:
+   a `JWTSecret` (`big-reference-seed` / dev secret) and an `Applicatie` with
+   `heeft_alle_autorisaties: true`. Idempotent, runs in the init container.
+2. **Seed the catalogus/zaaktype/eigenschap via the ZTC API** with an idempotent,
+   stdlib-only script (`infra/openzaak/seed_catalogus.py`, `make openzaak-seed`). It mints
+   a ZGW JWT from the provisioned client and matches existing objects (by `domein` /
+   `identificatie` / `naam`, querying `status=alles` so concepts are seen) before creating.
+3. **Keep the zaaktype a CONCEPT (not published).** Publishing pulls in roltypen,
+   statustypen and resultaattypen, which go beyond "schema-mandatory"; those arrive with
+   the workflow/zaak slices that actually need a published type. Listing uses `status=alles`.
+4. **Disable outbound notifications** (`NOTIFICATIONS_DISABLED=true`) until Open Notificaties
+   (NRC) lands in S-01-c — otherwise every ZTC write 500s trying to notify.
+5. **Fixed dev values:** RSIN `517439943` (elfproef-valid test value); the JWT secret is
+   dev-only and documented as such.
+
+## Consequences
+
+- **Reproducible & version-robust:** the API-driven seed doesn't depend on fixture PKs or
+  a catalogi `setup_configuration` step that may change between versions.
+- **Teaches the pattern:** the seed talks to OpenZaak exactly the way the ACL will later —
+  through the documented ZGW API, with a JWT (ADR-0001).
+- The seed is a script, but a **data loader is explicitly anticipated** (PRD §8); it lives
+  under `infra/openzaak/`, not as ad-hoc tooling.
+- **Follow-ups:** re-enable notifications when NRC is up (S-01-c); publish the zaaktype (add
+  the related types) when a slice needs to create real zaken; pin the OpenZaak image tag.
+
+## Alternatives considered
+
+- **Fully declarative in `data.yaml`** — rejected: no catalogi/zaaktype step exists.
+- **Django `loaddata` fixture** — rejected: brittle, tied to model PKs and the exact image
+  version; bypasses the API the rest of the system uses.

docs/index.md

@@ -0,0 +1,23 @@
+# register-referentie
+
+A reference application demonstrating Respellion's Common Ground architecture
+pattern. Quality and architectural clarity over feature throughput — every commit
+should teach.
+
+## Where to go
+
+- **[Product Requirements](PRD.md)** — what we're building and why.
+- **[ADR-0001: Loose coupling](architecture/adr-0001-loose-coupling.md)** — the
+  non-negotiable integration stance; the template for future ADRs.
+- **[Working in Gitea](gitea-workflow.md)** — issues, milestones, branches, PRs.
+- **[CI runbook](runbooks/ci.md)** — the pipeline and the `make ci` local gate.
+
+## Quickstart
+
+See the repository `README.md`. In short: clone, then either run the checks with
+`make ci`, or bring the BFF up with
+`docker compose -f infra/docker-compose.yml up -d --build --wait` and
+`curl http://localhost:8080/health`.
+
+> This site is built with MkDocs Material (`mkdocs build`). It grows with the
+> backlog; sections appear as their slices land.

docs/runbooks/flowable.md

@@ -0,0 +1,40 @@
+# Flowable runbook
+
+Flowable (`infra/flowable/docker-compose.yml`) runs the **flowable-rest** engine on
+Postgres. The `workflows/registratie.bpmn` model is deployed via the REST API at boot by
+the `flowable-init` container. Host port **:8090**; REST API under
+`http://localhost:8090/flowable-rest/service/` (basic auth **rest-admin / test**, dev only).
+
+## The model — `registratie`
+
+A minimal "Registratie ontvangen" process: **start → external-worker task
+`OpenZaakAanmaken` → end**. The external task is where the Workflow Client / ACL will
+later create the zaak in OpenZaak (S-04/S-05); for now a started instance parks there.
+
+## Quick test (`make`)
+
+```bash
+make flowable-up      # start engine + deploy registratie.bpmn on boot
+make flowable-smoke   # start + verify a new instance waits on the external task
+make flowable-down    # stop + wipe
+```
+
+`make flowable-smoke` runs `infra/flowable/verify.py`, which:
+1. waits for the `registratie` process definition to be deployed,
+2. starts an instance and asserts it did **not** end immediately,
+3. asserts an execution is parked at activity **`OpenZaakAanmaken`**,
+4. deletes the test instance.
+
+## Notes
+
+- **Deploy on boot** is idempotent: `flowable-init` skips if a deployment named
+  `registratie` already exists (so restarts on the same volume don't pile up versions).
+- **Dev creds:** `rest-admin` / `test`. Override via the flowable-rest app config for
+  anything beyond local dev.
+- **Image** `flowable/flowable-rest:latest` — pin a tag when stabilising.
+- Start an instance by hand:
+  ```bash
+  curl -s -u rest-admin:test -H 'Content-Type: application/json' \
+    -d '{"processDefinitionKey":"registratie"}' \
+    http://localhost:8090/flowable-rest/service/runtime/process-instances
+  ```

docs/runbooks/keycloak.md

@@ -0,0 +1,37 @@
+# Keycloak runbook
+
+Keycloak (`infra/keycloak/docker-compose.yml`) runs in dev mode with four realms
+imported at boot from `infra/keycloak/realms/`: **digid**, **eherkenning**, **eidas**,
+**medewerker**. It mocks the Dutch identity brokers so portals can do real OIDC logins
+locally. Host port **:8180**.
+
+## Quick test (`make`)
+
+```bash
+make keycloak-up      # start Keycloak + import realms (~30-60s first boot)
+make keycloak-smoke   # start + verify every realm logs in and returns its claim
+make keycloak-down    # stop + wipe
+```
+
+`make keycloak-smoke` runs `infra/keycloak/check_realms.py`, which does a password-grant
+login per realm and asserts the identifying claim:
+
+| Realm | User | Claim asserted |
+|---|---|---|
+| digid | jan-burger | `bsn` |
+| eherkenning | acme-ondernemer | `kvk` |
+| eidas | pierre-dupont | `eidas_id` |
+| medewerker | merel-behandelaar | role `behandelaar` |
+
+All test users / credentials are in [../synthetic-data.md](../synthetic-data.md).
+
+## Notes
+
+- **Admin console:** <http://localhost:8180/> — `admin` / `admin` (dev only).
+- **Client `big-portal`** is public with `standardFlowEnabled` (browser redirect login)
+  *and* `directAccessGrantsEnabled` (password grant, used by the smoke test).
+- **Dev store:** in-memory H2 via `start-dev`; realms re-import on each boot, so changes
+  made in the admin UI don't persist. Edit the realm JSONs to make durable changes.
+- **Image** pinned to `quay.io/keycloak/keycloak:26.1`.
+- Claims are injected by OIDC protocol mappers on `big-portal` (user attribute → token
+  claim); `medewerker` roles come through `realm_access.roles`.

docs/runbooks/opennotificaties.md

@@ -0,0 +1,44 @@
+# Open Notificaties (NRC) runbook
+
+The Open Notificaties stack (`infra/opennotificaties/docker-compose.yml`) is a lean
+adaptation of the upstream dev compose: PostGIS db, redis (also the Celery broker), a
+one-shot migrate-init, the API, and a celery worker. It shares the **`cg`** Docker
+network with the OpenZaak stack so the two can reach each other by service name.
+
+NRC is published on host **:8001** (OpenZaak holds :8000).
+
+## Quick test (`make`) — both platforms together
+
+```bash
+make stack-up      # OpenZaak + Open Notificaties on the shared network
+make stack-smoke   # start both + assert reachable (OZ 403/302/200, NRC 302)
+make stack-down    # stop + wipe both
+```
+
+`make stack-smoke` runs `docker compose -f infra/openzaak/... -f infra/opennotificaties/... up -d`
+and asserts:
+
+| Check | Expected |
+|---|---|
+| OpenZaak `GET /zaken/api/v1/zaken` (no JWT) | 403 (auth enforced) |
+| OpenZaak `GET /admin/` | 302 |
+| Open Notificaties `GET /admin/` | 302 |
+
+NRC admin UI: <http://localhost:8001/admin/> (dev superuser **admin / admin**).
+
+## Notification wiring is deferred to S-06
+
+Both platforms are **up and reachable**, but OpenZaak→NRC notification *delivery* is not
+wired yet, and OpenZaak still runs with `NOTIFICATIONS_DISABLED=true`. The bidirectional
+auth wiring (NRC `setup_configuration`: Services + Authorization to OpenZaak's
+Autorisaties API + JWT secrets + Kanalen + Abonnementen; OpenZaak's NotificationConfig)
+lands with **S-06 (Event Subscriber)** — the slice that actually consumes events. NRC's
+`setup_configuration/data.yaml` is intentionally minimal (migrations only) until then.
+
+This matches S-01's acceptance, which asks only that the platforms *come up in compose*
+and a health check confirms them reachable.
+
+## Prerequisites
+
+Same rootless-Podman setup as the rest of the repo — see [ci.md](ci.md) and
+[openzaak.md](openzaak.md). `systemctl --user start podman.socket` once per session.

docs/runbooks/openzaak.md

@@ -0,0 +1,75 @@
+# OpenZaak runbook
+
+The OpenZaak stack (`infra/openzaak/docker-compose.yml`) is a lean adaptation of the
+upstream open-zaak dev compose: PostGIS db, redis, a one-shot init that runs
+migrations, the OpenZaak API, and a celery worker.
+
+## Quick test (`make`)
+
+```bash
+make openzaak-up       # start the stack (first run pulls images + migrates: 1-3 min)
+make openzaak-smoke    # start + assert it's up with auth enforced (403/302/200)
+make openzaak-seed     # start + seed the BIG catalogus (idempotent)
+make openzaak-down     # stop and wipe data
+```
+
+## Seed the BIG catalogus
+
+`make openzaak-seed` brings the stack up and runs `infra/openzaak/seed_catalogus.py`,
+which creates (idempotently, via the ZTC API):
+
+- catalogus **BIG**
+- a lean **BIG-REGISTRATIE** zaaktype (concept; only schema-mandatory fields)
+- a **bsn** eigenschap on it
+
+then confirms the JWT client can list it. See **ADR-0002** for the design (why the
+zaaktype stays a concept, why notifications are disabled, why the API not a fixture).
+
+**JWT client** (provisioned declaratively by `setup_configuration/data.yaml`, **dev only**):
+
+| | |
+|---|---|
+| client_id | `big-reference-seed` |
+| secret | `insecure-dev-secret-change-me` |
+| authorizations | `heeft_alle_autorisaties` (all) |
+
+The seed mints a ZGW JWT (HS256) from these and calls `/catalogi/api/v1/...`.
+
+`make openzaak-smoke` polls until the API responds, then asserts:
+
+| Check | Expected |
+|---|---|
+| `GET /zaken/api/v1/zaken` (no JWT) | **403** — `PermissionDenied` ZGW fout (auth enforced) |
+| `GET /admin/` | **302** — admin login redirect |
+| `GET /zaken/api/v1/` | **200** — ZGW API schema root |
+
+> **403, not 401.** OpenZaak's ZGW APIs return `403 PermissionDenied` for a missing
+> or invalid JWT. The S-01 acceptance text says "401" — that's inaccurate; 403 is the
+> correct auth-enforced response.
+
+The admin UI is at <http://localhost:8000/admin/>; the dev superuser is **admin /
+admin** (from the compose env — dev only).
+
+## Prerequisites (rootless Podman)
+
+Same setup as the rest of the repo (see [ci.md](ci.md)):
+
+```bash
+systemctl --user start podman.socket    # the Docker-API socket the shim talks to
+```
+
+The Makefile auto-points `DOCKER_HOST` at the Podman socket when it exists, so the
+`make openzaak-*` targets work without extra env.
+
+## Notes
+
+- **Not in `make ci`.** The OpenZaak smoke is a separate, heavier check (large image
+  pull + migrations); it is intentionally kept out of `make ci` so the core gate
+  stays fast. Run `make openzaak-smoke` when you touch the OpenZaak stack.
+- **Notifications disabled.** `NOTIFICATIONS_DISABLED=true` — otherwise ZTC writes 500
+  trying to notify. Open Notificaties is now up (see [opennotificaties.md](opennotificaties.md)),
+  but OZ→NRC delivery wiring + re-enabling lands with **S-06**.
+- **Zaaktype is a concept**, not published (publishing needs roltypen/statustypen/
+  resultaattypen — beyond the lean seed). List with `?status=alles`.
+- **Image tag.** Currently `openzaak/open-zaak:latest` via `${OPENZAAK_TAG}`; pin to
+  a known-good tag (ADR-0002 follow-up).

docs/synthetic-data.md

@@ -0,0 +1,35 @@
+# Synthetic data
+
+All credentials here are **dev-only** synthetic test data — never real personal data,
+never used outside local development.
+
+## Keycloak realms (S-02)
+
+Keycloak runs at <http://localhost:8180> (admin console: **admin / admin**). Four realms
+are imported at boot from `infra/keycloak/realms/`. Each has a public OIDC client
+**`big-portal`** (standard flow + direct access grants enabled, redirect URIs `*` for dev).
+
+All test users share the password **`test123`**.
+
+| Realm | Mimics | User | Identifying claim |
+|---|---|---|---|
+| `digid` | DigiD (burgers) | `jan-burger` | `bsn` = `123456782` |
+| `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` |
+| `medewerker` | Internal staff | `tom-teamlead` | roles `behandelaar`, `teamlead` |
+
+The identifying claims are injected via OIDC protocol mappers on `big-portal`
+(user-attribute → token claim); `medewerker` roles appear in `realm_access.roles`.
+
+## Get a token (for testing)
+
+```bash
+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 -d scope=openid | jq -r .access_token
+```
+
+Decode the JWT payload to see the `bsn` claim. `make keycloak-smoke` checks every realm
+automatically.

infra/flowable/docker-compose.yml

@@ -0,0 +1,65 @@
+# Flowable (S-03): the flowable-rest engine on Postgres.
+# The registratie.bpmn model is deployed via the REST API on startup by flowable-init.
+#
+#   docker compose -f infra/flowable/docker-compose.yml up -d
+#   # REST API (basic auth) under http://localhost:8090/flowable-rest/service/
+#
+# Host port 8090 (8000/8001/8080/8180 are taken by OpenZaak/NRC/BFF/Keycloak).
+services:
+  flowable-db:
+    image: docker.io/library/postgres:16
+    environment:
+      POSTGRES_USER: flowable
+      POSTGRES_PASSWORD: flowable
+      POSTGRES_DB: flowable
+    volumes:
+      - flowable-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flowable -d flowable"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  flowable-rest:
+    image: docker.io/flowable/flowable-rest:latest
+    environment:
+      SPRING_DATASOURCE_DRIVER-CLASS-NAME: org.postgresql.Driver
+      SPRING_DATASOURCE_URL: jdbc:postgresql://flowable-db:5432/flowable
+      SPRING_DATASOURCE_USERNAME: flowable
+      SPRING_DATASOURCE_PASSWORD: flowable
+    ports:
+      - "8090:8080"
+    depends_on:
+      flowable-db:
+        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.
+  flowable-init:
+    image: docker.io/curlimages/curl:latest
+    restart: "no"
+    volumes:
+      - ../../workflows/registratie.bpmn:/work/registratie.bpmn: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"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+        fi
+    depends_on:
+      flowable-rest:
+        condition: service_started
+    networks: [cg]
+
+volumes:
+  flowable-db:
+
+networks:
+  cg:

infra/flowable/verify.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Smoke-check Flowable: the registratie process is deployed, and starting an
+instance parks it on the OpenZaakAanmaken external task. Stdlib only.
+"""
+import base64, json, sys, time, urllib.error, urllib.request
+
+BASE = "http://localhost:8090/flowable-rest/service"
+AUTH = "Basic " + base64.b64encode(b"rest-admin:test").decode()
+
+
+def call(method, path, payload=None):
+    data = json.dumps(payload).encode() if payload is not None else None
+    req = urllib.request.Request(BASE + path, data=data, method=method, headers={
+        "Authorization": AUTH, "Content-Type": "application/json", "Accept": "application/json"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return r.status, json.loads(r.read() or "null")
+
+
+def main():
+    # 1. process definition deployed? (wait for the async init-container deploy)
+    defs = {"total": 0}
+    for _ in range(40):
+        _, defs = call("GET", "/repository/process-definitions?key=registratie")
+        if defs["total"] >= 1:
+            break
+        time.sleep(3)
+    assert defs["total"] >= 1, "registratie process definition not deployed"
+    print(f"process definition 'registratie' deployed (total={defs['total']})")
+
+    # 2. start an instance
+    st, pi = call("POST", "/runtime/process-instances", {"processDefinitionKey": "registratie"})
+    assert st == 201, f"start failed: {st} {pi}"
+    pid = pi["id"]
+    assert pi.get("ended") is False, "instance ended immediately — external task not reached"
+    print(f"started instance {pid} (ended={pi.get('ended')})")
+
+    # 3. waiting on the external task?
+    _, ex = call("GET", f"/runtime/executions?processInstanceId={pid}")
+    activities = [e.get("activityId") for e in ex["data"]]
+    assert "OpenZaakAanmaken" in activities, f"not waiting at OpenZaakAanmaken: {activities}"
+    print(f"instance is waiting at the external task: {activities}")
+
+    # 4. cleanup
+    try:
+        call("DELETE", f"/runtime/process-instances/{pid}")
+        print("cleaned up instance")
+    except urllib.error.HTTPError:
+        pass
+
+    print("flowable smoke OK")
+
+
+if __name__ == "__main__":
+    main()

infra/keycloak/check_realms.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Smoke-check the Keycloak realms: each realm's OIDC login works (password grant)
+and returns its expected identifying claim. Stdlib only. Exits non-zero on failure.
+"""
+import base64, json, sys, urllib.error, urllib.parse, urllib.request
+
+BASE = "http://localhost:8180"
+CLIENT = "big-portal"
+PWD = "test123"
+
+# realm, user, claim ("__roles__" => check realm_access.roles), expected-contains
+CHECKS = [
+    ("digid", "jan-burger", "bsn", "123456782"),
+    ("eherkenning", "acme-ondernemer", "kvk", "12345678"),
+    ("eidas", "pierre-dupont", "eidas_id", "FR/NL"),
+    ("medewerker", "merel-behandelaar", "__roles__", "behandelaar"),
+]
+
+
+def decode(jwt):
+    p = jwt.split(".")[1]
+    p += "=" * (-len(p) % 4)
+    return json.loads(base64.urlsafe_b64decode(p))
+
+
+def grant(realm, user):
+    data = urllib.parse.urlencode({
+        "grant_type": "password", "client_id": CLIENT,
+        "username": user, "password": PWD, "scope": "openid",
+    }).encode()
+    req = urllib.request.Request(
+        f"{BASE}/realms/{realm}/protocol/openid-connect/token", data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"})
+    with urllib.request.urlopen(req, timeout=20) as r:
+        return json.loads(r.read())
+
+
+def main():
+    ok = True
+    for realm, user, claim, expect in CHECKS:
+        try:
+            at = decode(grant(realm, user)["access_token"])
+            if claim == "__roles__":
+                val = at.get("realm_access", {}).get("roles", [])
+                good = expect in val
+            else:
+                val = at.get(claim)
+                good = val is not None and expect in str(val)
+            print(f"{realm:12} {user:18} login OK | {claim} = {val} "
+                  f"[{'OK' if good else 'UNEXPECTED'}]")
+            ok = ok and good
+        except urllib.error.HTTPError as e:
+            ok = False
+            print(f"{realm:12} {user:18} LOGIN FAILED {e.code}: {e.read()[:200]!r}")
+    print("keycloak smoke OK" if ok else "keycloak smoke FAILED")
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

infra/keycloak/docker-compose.yml

@@ -0,0 +1,29 @@
+# Keycloak (S-02) with four pre-seeded realms imported at boot:
+#   digid · eherkenning · eidas · medewerker
+# Dev mode, H2 in-memory store, realm JSONs imported from ./realms.
+#
+#   docker compose -f infra/keycloak/docker-compose.yml up -d
+#   curl -s -o /dev/null -w '%{http_code}\n' \
+#     http://localhost:8180/realms/digid/.well-known/openid-configuration   # -> 200
+#
+# Admin console: http://localhost:8180/  (admin / admin — dev only)
+services:
+  keycloak:
+    image: quay.io/keycloak/keycloak:26.1
+    command: ["start-dev", "--import-realm"]
+    environment:
+      KC_BOOTSTRAP_ADMIN_USERNAME: admin
+      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
+      # Older var names too, harmless on 26.x:
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: admin
+      KC_HEALTH_ENABLED: "true"
+      KC_HTTP_ENABLED: "true"
+    ports:
+      - "8180:8080"
+    volumes:
+      - ./realms:/opt/keycloak/data/import:ro,z
+    networks: [cg]
+
+networks:
+  cg:

infra/keycloak/realms/digid-realm.json

@@ -0,0 +1,43 @@
+{
+  "realm": "digid",
+  "enabled": true,
+  "displayName": "Mock DigiD",
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"],
+      "protocolMappers": [
+        {
+          "name": "bsn",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-attribute-mapper",
+          "config": {
+            "user.attribute": "bsn",
+            "claim.name": "bsn",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    }
+  ],
+  "users": [
+    {
+      "username": "jan-burger",
+      "enabled": true,
+      "firstName": "Jan",
+      "lastName": "Burger",
+      "email": "jan.burger@example.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "attributes": { "bsn": ["123456782"] }
+    }
+  ]
+}

infra/keycloak/realms/eherkenning-realm.json

@@ -0,0 +1,43 @@
+{
+  "realm": "eherkenning",
+  "enabled": true,
+  "displayName": "Mock eHerkenning",
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"],
+      "protocolMappers": [
+        {
+          "name": "kvk",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-attribute-mapper",
+          "config": {
+            "user.attribute": "kvk",
+            "claim.name": "kvk",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    }
+  ],
+  "users": [
+    {
+      "username": "acme-ondernemer",
+      "enabled": true,
+      "firstName": "Anita",
+      "lastName": "Ondernemer",
+      "email": "anita@acme.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "attributes": { "kvk": ["12345678"] }
+    }
+  ]
+}

infra/keycloak/realms/eidas-realm.json

@@ -0,0 +1,43 @@
+{
+  "realm": "eidas",
+  "enabled": true,
+  "displayName": "Mock eIDAS",
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"],
+      "protocolMappers": [
+        {
+          "name": "eidas_id",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-attribute-mapper",
+          "config": {
+            "user.attribute": "eidas_id",
+            "claim.name": "eidas_id",
+            "jsonType.label": "String",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ]
+    }
+  ],
+  "users": [
+    {
+      "username": "pierre-dupont",
+      "enabled": true,
+      "firstName": "Pierre",
+      "lastName": "Dupont",
+      "email": "pierre.dupont@example.fr",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "attributes": { "eidas_id": ["FR/NL/AB-1234-5678"] }
+    }
+  ]
+}

infra/keycloak/realms/medewerker-realm.json

@@ -0,0 +1,44 @@
+{
+  "realm": "medewerker",
+  "enabled": true,
+  "displayName": "Medewerkers",
+  "roles": {
+    "realm": [
+      { "name": "behandelaar", "description": "Behandelt registratieaanvragen" },
+      { "name": "teamlead", "description": "Teamleider behandeling" }
+    ]
+  },
+  "clients": [
+    {
+      "clientId": "big-portal",
+      "enabled": true,
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": true,
+      "redirectUris": ["*"],
+      "webOrigins": ["*"]
+    }
+  ],
+  "users": [
+    {
+      "username": "merel-behandelaar",
+      "enabled": true,
+      "firstName": "Merel",
+      "lastName": "Behandelaar",
+      "email": "merel@big.example.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "realmRoles": ["behandelaar"]
+    },
+    {
+      "username": "tom-teamlead",
+      "enabled": true,
+      "firstName": "Tom",
+      "lastName": "Teamlead",
+      "email": "tom@big.example.nl",
+      "emailVerified": true,
+      "credentials": [{ "type": "password", "value": "test123", "temporary": false }],
+      "realmRoles": ["behandelaar", "teamlead"]
+    }
+  ]
+}

infra/opennotificaties/docker-compose.yml

@@ -0,0 +1,91 @@
+# Open Notificaties (NRC) stack (S-01-c). Lean adaptation of the upstream dev compose:
+# db (PostGIS) + redis (also the Celery broker) + migrate-init + the API + a celery worker.
+#
+# Shares the `cg` network with the OpenZaak stack so the two can reach each other.
+# Run BOTH together (NRC needs OpenZaak's Autorisaties API for auth wiring):
+#
+#   docker compose -f infra/openzaak/docker-compose.yml -f infra/opennotificaties/docker-compose.yml up -d
+#   curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8001/admin/   # -> 302
+#
+# NRC is published on host :8001 (OpenZaak holds :8000).
+services:
+  nrc-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: opennotificaties
+      POSTGRES_PASSWORD: opennotificaties
+      POSTGRES_DB: opennotificaties
+    command: postgres -c max_connections=300
+    volumes:
+      - nrc-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U opennotificaties -d opennotificaties"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  nrc-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  nrc-init:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-latest}
+    environment: &nrc-env
+      DJANGO_SETTINGS_MODULE: nrc.conf.docker
+      SECRET_KEY: ${NRC_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: nrc-db
+      DB_NAME: opennotificaties
+      DB_USER: opennotificaties
+      DB_PASSWORD: opennotificaties
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: nrc-redis:6379/0
+      CACHE_AXES: nrc-redis:6379/0
+      CELERY_BROKER_URL: redis://nrc-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://nrc-redis:6379/1
+      DISABLE_2FA: "true"
+      OPENNOTIFICATIES_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENNOTIFICATIES_SUPERUSER_EMAIL: admin@localhost
+      RUN_SETUP_CONFIG: "true"
+    command: /setup_configuration.sh
+    volumes:
+      - ./setup_configuration:/app/setup_configuration:ro,z
+    depends_on:
+      nrc-db:
+        condition: service_healthy
+      nrc-redis:
+        condition: service_started
+    networks: [cg]
+
+  nrc-web:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-latest}
+    environment: *nrc-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8001:8000"
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  nrc-celery:
+    image: docker.io/openzaak/open-notificaties:${OPENNOTIFICATIES_TAG:-latest}
+    environment: *nrc-env
+    command: /celery_worker.sh
+    depends_on:
+      nrc-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+volumes:
+  nrc-db:
+
+networks:
+  cg:

infra/opennotificaties/setup_configuration/data.yaml

@@ -0,0 +1,5 @@
+# Open Notificaties setup_configuration.
+# Stage 1 (this commit): intentionally minimal — the init container runs
+# migrations; no steps enabled yet. The OpenZaak<->NRC notification wiring
+# (Services, Authorization, JWT, Kanalen) is added next. See ADR-0002 / S-01-c.
+{}

infra/openzaak/docker-compose.yml

@@ -0,0 +1,95 @@
+# OpenZaak stack (S-01). Lean adaptation of the upstream open-zaak dev compose:
+# db (PostGIS) + redis + a one-shot init (migrations) + the API + a celery worker.
+# Dropped from upstream for leanness: nginx, celery-beat, flower, OTEL.
+#
+#   docker compose -f infra/openzaak/docker-compose.yml up -d --wait
+#   curl -i http://localhost:8000/zaken/api/v1/zaken   # -> 401 (auth required)
+#
+# NOTE: image pinned to a tag (not :latest) once a known-good tag is chosen; see
+# the catalogus-design ADR. Using a tag var with a sensible default for now.
+services:
+  oz-db:
+    image: docker.io/postgis/postgis:17-3.5
+    environment:
+      POSTGRES_USER: openzaak
+      POSTGRES_PASSWORD: openzaak
+      POSTGRES_DB: openzaak
+    command: postgres -c max_connections=300
+    volumes:
+      - oz-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U openzaak -d openzaak"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  oz-redis:
+    image: docker.io/library/redis:7
+    networks: [cg]
+
+  oz-init:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    environment: &oz-env
+      DJANGO_SETTINGS_MODULE: openzaak.conf.docker
+      SECRET_KEY: ${OZ_SECRET_KEY:-dev-only-not-for-production}
+      DB_HOST: oz-db
+      DB_NAME: openzaak
+      DB_USER: openzaak
+      DB_PASSWORD: openzaak
+      IS_HTTPS: "no"
+      ALLOWED_HOSTS: "*"
+      CACHE_DEFAULT: oz-redis:6379/0
+      CACHE_AXES: oz-redis:6379/0
+      CELERY_BROKER_URL: redis://oz-redis:6379/1
+      CELERY_RESULT_BACKEND: redis://oz-redis:6379/1
+      DISABLE_2FA: "true"
+      # Notifications go to Open Notificaties (NRC), which arrives in S-01-c.
+      # Until then, disable outbound notifications so writes don't 500.
+      NOTIFICATIONS_DISABLED: "true"
+      OPENZAAK_SUPERUSER_USERNAME: admin
+      DJANGO_SUPERUSER_PASSWORD: admin
+      OPENZAAK_SUPERUSER_EMAIL: admin@localhost
+      RUN_SETUP_CONFIG: "true"
+    command: /setup_configuration.sh
+    volumes:
+      # :z relabels for SELinux; the dir/file must be world-readable for the
+      # container user (rootless Podman uid mapping). See docs/runbooks/openzaak.md.
+      - ./setup_configuration:/app/setup_configuration:ro,z
+    depends_on:
+      oz-db:
+        condition: service_healthy
+      oz-redis:
+        condition: service_started
+    networks: [cg]
+
+  openzaak:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    environment: *oz-env
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests,sys; sys.exit(0 if requests.head('http://localhost:8000/admin/').status_code in (200,302) else 1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    ports:
+      - "8000:8000"
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+  oz-celery:
+    image: docker.io/openzaak/open-zaak:${OPENZAAK_TAG:-latest}
+    environment: *oz-env
+    command: /celery_worker.sh
+    depends_on:
+      oz-init:
+        condition: service_completed_successfully
+    networks: [cg]
+
+volumes:
+  oz-db:
+
+networks:
+  cg:

infra/openzaak/seed_catalogus.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Idempotent seed of the BIG catalogus into OpenZaak via the ZTC API.
+
+Creates (if absent):
+  - catalogus "BIG"
+  - a lean "BIG-registratie" zaaktype (only schema-mandatory fields)
+  - a "bsn" eigenschap on that zaaktype
+  - then publishes the zaaktype.
+
+Auth uses the JWT client provisioned by setup_configuration (see ADR-0002).
+Stdlib only — no pip deps. Re-running is safe (matches existing by identifier).
+"""
+import base64, hashlib, hmac, json, os, sys, time, urllib.error, urllib.request
+
+BASE = os.environ.get("OZ_BASE", "http://localhost:8000")
+CLIENT_ID = os.environ.get("OZ_CLIENT_ID", "big-reference-seed")
+SECRET = os.environ.get("OZ_SECRET", "insecure-dev-secret-change-me")
+ZTC = f"{BASE}/catalogi/api/v1"
+RSIN = "517439943"  # elfproef-valid test RSIN
+
+
+def token():
+    b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=")
+    hdr = {"alg": "HS256", "typ": "JWT"}
+    pl = {"iss": CLIENT_ID, "iat": int(time.time()), "client_id": CLIENT_ID,
+          "user_id": "seed", "user_representation": "seed"}
+    seg = b64(json.dumps(hdr, separators=(",", ":")).encode()) + b"." + \
+          b64(json.dumps(pl, separators=(",", ":")).encode())
+    sig = b64(hmac.new(SECRET.encode(), seg, hashlib.sha256).digest())
+    return (seg + b"." + sig).decode()
+
+
+def api(method, path, body=None):
+    url = path if path.startswith("http") else f"{ZTC}{path}"
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method, headers={
+        "Authorization": "Bearer " + token(),
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    })
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return r.status, json.loads(r.read() or "null")
+    except urllib.error.HTTPError as e:
+        return e.code, json.loads(e.read() or "null")
+
+
+def find(path):
+    status, body = api("GET", path)
+    if status != 200:
+        sys.exit(f"GET {path} -> {status}: {body}")
+    return body.get("results", [])
+
+
+def main():
+    # 1. Catalogus
+    existing = [c for c in find(f"/catalogussen?domein=BIG") if c.get("domein") == "BIG"]
+    if existing:
+        cat = existing[0]
+        print(f"skip   catalogus BIG ({cat['url']})")
+    else:
+        st, cat = api("POST", "/catalogussen", {
+            "domein": "BIG", "rsin": RSIN,
+            "contactpersoonBeheerNaam": "BIG Beheer",
+        })
+        if st != 201:
+            sys.exit(f"create catalogus -> {st}: {cat}")
+        print(f"create catalogus BIG ({cat['url']})")
+
+    # 2. Zaaktype (concept)
+    # status=alles so concept zaaktypen are matched too (else we'd duplicate).
+    zts = [z for z in find(f"/zaaktypen?catalogus={cat['url']}&status=alles")
+           if z.get("identificatie") == "BIG-REGISTRATIE"]
+    if zts:
+        zt = zts[0]
+        print(f"skip   zaaktype BIG-REGISTRATIE ({zt['url']}) concept={zt.get('concept')}")
+    else:
+        st, zt = api("POST", "/zaaktypen", {
+            "identificatie": "BIG-REGISTRATIE",
+            "omschrijving": "BIG-registratie",
+            "vertrouwelijkheidaanduiding": "openbaar",
+            "doel": "Registratie van een zorgprofessional in het BIG-register",
+            "aanleiding": "Aanvraag tot registratie",
+            "indicatieInternOfExtern": "extern",
+            "handelingInitiator": "indienen",
+            "onderwerp": "BIG-registratie",
+            "handelingBehandelaar": "behandelen",
+            "doorlooptijd": "P30D",
+            "opschortingEnAanhoudingMogelijk": False,
+            "verlengingMogelijk": False,
+            "publicatieIndicatie": False,
+            "productenOfDiensten": [],
+            "referentieproces": {"naam": "BIG-registratie"},
+            "catalogus": cat["url"],
+            "besluittypen": [],
+            "gerelateerdeZaaktypen": [],
+            "beginGeldigheid": "2026-01-01",
+            "versiedatum": "2026-01-01",
+            "verantwoordelijke": RSIN,
+        })
+        if st != 201:
+            sys.exit(f"create zaaktype -> {st}: {json.dumps(zt, indent=2)}")
+        print(f"create zaaktype BIG-REGISTRATIE ({zt['url']})")
+
+    # 3. bsn eigenschap (only addable while concept)
+    eigs = [e for e in find(f"/eigenschappen?zaaktype={zt['url']}&status=alles")
+            if e.get("naam") == "bsn"]
+    if eigs:
+        print("skip   eigenschap bsn")
+    elif zt.get("concept", True):
+        st, eig = api("POST", "/eigenschappen", {
+            "naam": "bsn",
+            "definitie": "Burgerservicenummer van de zorgprofessional",
+            "zaaktype": zt["url"],
+            "specificatie": {"groep": "aanvrager", "formaat": "tekst",
+                             "lengte": "9", "kardinaliteit": "1", "waardenverzameling": []},
+        })
+        if st != 201:
+            sys.exit(f"create eigenschap -> {st}: {json.dumps(eig, indent=2)}")
+        print("create eigenschap bsn")
+    else:
+        print("warn   zaaktype already published; cannot add bsn eigenschap")
+
+    # Intentionally NOT published. Publishing requires roltypen, resultaattypen
+    # and statustypen, which go beyond the "lean / schema-mandatory" zaaktype this
+    # slice asks for; they arrive with the workflow/zaak slices. See ADR-0002.
+
+    # 4. Verify the JWT client can list the zaaktype (concepts included).
+    zaaktypen = find(f"/zaaktypen?catalogus={cat['url']}&status=alles")
+    names = [z.get("identificatie") for z in zaaktypen]
+    print(f"zaaktypen in BIG: {names}")
+    assert "BIG-REGISTRATIE" in names, "BIG-REGISTRATIE not listed"
+    print("OK — BIG catalogus seeded (BIG-REGISTRATIE concept + bsn eigenschap)")
+
+
+if __name__ == "__main__":
+    main()

infra/openzaak/setup_configuration/data.yaml

@@ -0,0 +1,22 @@
+# OpenZaak setup_configuration (idempotent, declarative).
+# Provisions the JWT client the seed + ACL use to call OpenZaak's APIs.
+# Dev-only credentials — not for production.
+#
+# Steps come from vng_api_common.contrib.setup_configuration (see ADR-0002).
+
+vng_api_common_credentials_config_enable: true
+vng_api_common_credentials:
+  items:
+    - identifier: big-reference-seed
+      secret: insecure-dev-secret-change-me
+
+vng_api_common_applicaties_config_enable: true
+vng_api_common_applicaties:
+  items:
+    # uuid must be given explicitly as a string (the step's auto-default is a
+    # UUID object that fails its own validation).
+    - uuid: "11111111-1111-4111-8111-111111111111"
+      client_ids:
+        - big-reference-seed
+      label: BIG reference seed client
+      heeft_alle_autorisaties: true

mkdocs.yml

@@ -0,0 +1,41 @@
+site_name: register-referentie
+site_description: Reference application for Respellion's Common Ground architecture pattern
+docs_dir: docs
+
+theme:
+  name: material
+  features:
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - Product Requirements: PRD.md
+  - Architecture:
+      - "ADR-0001: Loose coupling": architecture/adr-0001-loose-coupling.md
+  - Working in Gitea: gitea-workflow.md
+  - Runbooks:
+      - CI: runbooks/ci.md
+
+markdown_extensions:
+  - admonition
+  - toc:
+      permalink: true
+  - pymdownx.superfences
+
+# Many docs referenced by PRD.md land in later slices; don't fail the build on them.
+validation:
+  nav:
+    omitted_files: warn
+  links:
+    not_found: warn

workflows/registratie.bpmn

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
+             xmlns:flowable="http://flowable.org/bpmn"
+             xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+             xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC"
+             xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI"
+             targetNamespace="http://respellion.nl/big">
+
+  <!-- S-03: minimal "Registratie ontvangen" flow.
+       start -> external-worker task (OpenZaakAanmaken) -> end.
+       The external task is handled by the Workflow Client / ACL in later slices. -->
+  <process id="registratie" name="Registratie ontvangen" isExecutable="true">
+
+    <startEvent id="start" name="Registratie ontvangen"/>
+
+    <sequenceFlow id="flow1" sourceRef="start" targetRef="OpenZaakAanmaken"/>
+
+    <serviceTask id="OpenZaakAanmaken" name="OpenZaak aanmaken"
+                 flowable:type="external-worker"
+                 flowable:topic="OpenZaakAanmaken"/>
+
+    <sequenceFlow id="flow2" sourceRef="OpenZaakAanmaken" targetRef="end"/>
+
+    <endEvent id="end" name="Zaak aangemaakt"/>
+  </process>
+
+  <bpmndi:BPMNDiagram id="diagram">
+    <bpmndi:BPMNPlane id="plane" bpmnElement="registratie">
+      <bpmndi:BPMNShape id="s_start" bpmnElement="start">
+        <omgdc:Bounds x="100" y="100" width="30" height="30"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="s_task" bpmnElement="OpenZaakAanmaken">
+        <omgdc:Bounds x="200" y="85" width="120" height="60"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="s_end" bpmnElement="end">
+        <omgdc:Bounds x="400" y="100" width="30" height="30"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="e_flow1" bpmnElement="flow1">
+        <omgdi:waypoint x="130" y="115"/>
+        <omgdi:waypoint x="200" y="115"/>
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="e_flow2" bpmnElement="flow2">
+        <omgdi:waypoint x="320" y="115"/>
+        <omgdi:waypoint x="400" y="115"/>
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</definitions>