feat(infra): seed BIG catalogus + JWT client for OpenZaak (refs #2) (#41)

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.