register-referentie/docs/PRD.md

BIG-Register Reference Application — PRD

Status: v1 draft
Owner: Respellion
Primary remote: Gitea (self-hosted, Respellion)
Purpose: A reference application that demonstrates Respellion's Common Ground architecture pattern — using OpenZaak and other Common Ground modules behind a loose-coupling anti-corruption layer, with workflow, scheduling, and data governance as peer modules. It serves as a Foundations playbook artefact and as a credible, runnable demonstrator for Dutch public-sector engagements.

---

1. Goals

1. Demonstrate that a domain-specific case management application (a BIG-style register) can be built on top of unforked Common Ground modules by isolating all domain shaping in an Anti-Corruption Layer.
2. Show four end-user portals (self-service, public register, back-office, maintenance) sharing one domain layer through a BFF.
3. Show process orchestration via Flowable as a peer module, with BPMN + DMN governing the registration workflow.
4. Show data governance and GDPR lineage as a separate, integratable module (later iteration).
5. Be fully runnable locally with docker compose up, including all upstream Common Ground modules, identity, workflow engine, and synthetic data.
6. Encode Respellion craft defaults: TDD, DDD, BDD, mutation testing, trunk-based development, Conventional Commits, ADRs, and CI gates.
7. Run end-to-end on Gitea infrastructure — source, issues, CI, container registry, releases, wiki — to demonstrate EU-sovereign tooling.

2. Non-goals

• Not a certified production system. No real DigiD/eHerkenning/eIDAS — mocked via Keycloak.
• Not a multi-tenant SaaS. One instance, one client persona, per deployment.
• Not feature-complete to the real Dutch BIG-register. Modelled as a plausible analogue, not a copy.
• Not optimised for production scale; correctness and architectural clarity beat throughput.
• Not dependent on GitHub. The repository lives on a Respellion Gitea instance; GitHub mirroring is explicitly out of scope unless added later as an outreach measure.

3. Architecture summary

Refer to docs/architecture/ for diagrams. Briefly:

• Portals (Angular, NL Design System): self-service, openbaar register, behandel-portal, beheer-portal — four apps in an Nx monorepo with a shared component library.
• BFF (.NET): per-portal aggregation, OIDC token validation, audit, rate-limiting.
• BIG Domain Service (.NET): DDD aggregates, registration workflow, eligibility rules, orchestrates ACL and workflow engine.
• Anti-Corruption Layer (.NET): the only code that knows about ZGW APIs. Default-fills schema-mandatory fields, maps domain ↔ ZGW vocabulary.
• Workflow Client (.NET): REST client to Flowable; acts as external-task job worker so BPMN never reaches into OpenZaak.
• Event Subscriber (.NET): consumes NRC webhooks, updates the read projection, correlates events to running Flowable processes.
• Read Projection Store: denormalised, public-safe view feeding the openbaar register portal.
• Scheduler (Quartz.NET): fleet-wide sweeps (expiry, reminders).
• Common Ground modules (upstream, unforked): OpenZaak, Open Notificaties, Open Klant, Objecten + Objecttypen, Autorisaties.
• Flowable: BPMN + DMN engines with Postgres-backed jobs.
• Identity: Keycloak realms standing in for DigiD, eHerkenning, eIDAS, and a medewerker-IdP.
• Data Governance (later): OpenMetadata as a separate module, ingesting from read replicas and via a lineage SDK.

4. User types and primary scenarios

User type	Auth	Portal	Primary scenario
Zorgprofessional	DigiD (mock)	Self-Service	Submit registration, upload diploma, track status
Werkgever / Onderwijsinstelling	eHerkenning (mock)	Self-Service	Register on behalf of a professional (machtiging)
EU-professional	eIDAS (mock)	Self-Service	Foreign diploma registration with extra checks
Burger / Werkgever-check	anonymous	Openbaar Register	Lookup a professional's registration status
Behandelaar / Jurist	medewerker-IdP	Behandel-Portal	Review cases, request additional documents, decide
Beheerder	medewerker-IdP + MFA	Beheer-Portal	Manage catalogus, configure default-fill rules, monitor

5. Functional scope — flows for v1

1. Happy path registration — DigiD login, submit, upload diploma, automatic verification passes, behandelaar approves, register entry published.
2. Document timeout — registration submitted, no diploma uploaded within 30 days, automatic cancellation.
3. Withdrawal — applicant withdraws before decision; case cancelled with audit trail.
4. Foreign diploma escalation — eIDAS login, diploma flagged as foreign, additional CBGV-style assessment step.
5. Beoordeling escalation — behandelaar does not pick up within 14 days, case escalates to teamlead.

The five flows form the BDD acceptance backbone (Gherkin scenarios in tests/acceptance/).

6. Synthetic data

• Fixed seed loaded on first start: 5–10 hand-crafted personas covering all five flows, plus ~50 register entries with diverse statuses to populate the openbaar register.
• Dutch-realistic names; valid test-BSN range documented in docs/synthetic-data.md.
• Diplomas: PDF placeholders with deterministic content, generated by a small data-loader service on first compose-up.
• Re-seeding: a make seed / pwsh ./tools/seed.ps1 target rebuilds from scratch.

7. Non-functional requirements

• Local startup: docker compose up brings everything green within 3 minutes on a developer machine.
• CI gates (Gitea Actions): lint, unit, integration, mutation (with ratchet), e2e for the current flow, container build pushed to Gitea Container Registry, compose-up smoke test.
• TDD discipline: red → green → refactor commits visible in history.
• Mutation testing: Stryker.NET (backend) and Stryker (Angular), baseline-ratcheted on main.
• Coverage: not a target; mutation score is the quality signal.
• Observability: structured logs (Serilog), OpenTelemetry traces, Prometheus metrics; a local Grafana with pre-built dashboards.
• Security: all secrets in Gitea repository/organisation secrets or local .env (gitignored); no secrets in repo. OWASP dependency scanning step in the Gitea Actions pipeline.
• Conventional Commits + git-cliff generated changelog. CalVer versioning.

8. Technology choices (locked)

• Source control & collaboration: Gitea (Respellion self-hosted) — repository, issues, milestones, labels, projects, releases, container registry, wiki, packages.
• CI/CD: Gitea Actions running on Respellion-hosted act_runner instances. Workflow files live in .gitea/workflows/. Marketplace actions are referenced via absolute URLs (uses: https://github.com/actions/checkout@v4 or Gitea-hosted equivalents where available) for reproducibility.
• Backend: .NET 10 (LTS at iteration time), C#, minimal APIs for BFF, MediatR for in-process messaging within Domain Service, EF Core for the projection store and domain DB.
• Frontend: Angular (latest LTS) + TypeScript, standalone components + signals, Nx monorepo, NL Design System component library, Angular Testing Library + Playwright.
• Workflow: Flowable (BPMN + DMN) via Docker image; Postgres for engine store.
• Identity: Keycloak with pre-seeded realms.
• Common Ground: official upstream Docker images for OpenZaak, Open Notificaties, Open Klant, Objecten, Objecttypen, Autorisaties.
• Datastore: Postgres for all .NET services; one schema per service.
• Scheduler: Quartz.NET inside the Domain Service deployment.
• Container registry: Gitea's built-in container registry; image references in compose pin to gitea.respellion.local/big-reference/<service>:<tag>.
• Containers: Docker for all components; compose for local; Helm chart sketch for production aspirations (not deployed as part of v1).
• Docs: MkDocs Material plus Gitea's built-in wiki for living operational pages. See §10.
• Languages of artefacts: code, commits, ADRs, docs in English; user-facing portal copy and glossary terms in Dutch.

9. Repository structure (high-level)

/
├── apps/                       # Angular portals (Nx)
│   ├── self-service/
│   ├── openbaar/
│   ├── behandel/
│   └── beheer/
├── libs/                       # shared Angular libs (UI, auth, api-client)
├── services/                   # .NET services
│   ├── bff/
│   ├── domain/                 # BIG Domain Service
│   ├── acl/                    # standalone ACL library + service
│   ├── event-subscriber/
│   └── projection-api/
├── workflows/                  # BPMN + DMN sources, exported and version-controlled
├── infra/
│   ├── docker-compose.yml
│   ├── keycloak/
│   ├── opennotificaties/
│   ├── openzaak/
│   ├── objecten/
│   ├── flowable/
│   └── seed/                   # data loader
├── tests/
│   ├── acceptance/             # Gherkin / Reqnroll BDD scenarios
│   └── e2e/                    # Playwright
├── docs/                       # static docs (MkDocs source)
│   ├── PRD.md
│   ├── architecture/           # diagrams + ADRs
│   ├── runbooks/
│   ├── synthetic-data.md
│   └── gitea-workflow.md       # how we use Gitea for issues/milestones/projects
├── .gitea/
│   ├── workflows/              # Gitea Actions YAML
│   └── ISSUE_TEMPLATE/         # issue templates (slice, bug, ADR-proposal)
├── CLAUDE.md                   # working agreements
├── BACKLOG.md                  # pointer + mirror of the active Gitea milestone backlog
└── README.md

10. Documentation strategy — split between static and living docs

Two surfaces, each with a clear role:

Static, versioned documentation — docs/ rendered by MkDocs Material.

• The PRD, architecture diagrams (Mermaid sources in repo), ADRs, glossary, synthetic-data spec, and runbooks live here.
• Source of truth, versioned with the code, reviewed via PR.
• Published artefact: an MkDocs site built by a Gitea Actions workflow on every push to main and exposed via Gitea Pages (or a static-files job uploading to a Respellion-hosted location).
• ADRs use the Nygard template, one decision per file (adr-NNNN-title.md). First ADR (adr-0001-loose-coupling.md) is provided as a template.

Living, operational documentation — Gitea Wiki.

• The Gitea project's built-in Wiki holds operational pages that change frequently and where in-place editing matters: the day-to-day runbook, "known issues right now," the on-call rota, environment URLs, and the human-readable view of the iteration backlog.
• The Wiki is not the source of truth for architecture or ADRs — those stay in docs/. The Wiki points at them.
• The Wiki is part of the deliverable and is reviewed alongside the code.

Why split: versioned docs benefit from PR review and ship with the code; operational pages benefit from in-UI editing and don't need a full PR cycle. Treating both as legitimate gives each its proper home.

11. Story and backlog management — Gitea is the system of record

User stories, defects, technical debt, and ADR proposals are tracked in Gitea Issues. The BACKLOG.md file in the repo is a curated mirror of the current milestone — it exists so that Claude Code and contributors can read the iteration plan without opening the web UI, but the system of record is Gitea.

Concrete conventions:

• Each slice in BACKLOG.md corresponds 1:1 to a Gitea issue with the same S-NN identifier in the title (e.g. S-04 · ACL skeleton with one operation: open a zaak).
• Milestones group slices into iterations: Iteration 0 — Foundations, Iteration 1 — Walking Skeleton, etc.
• Labels classify work: type:slice, type:bug, type:adr-proposal, type:chore, plus area labels (area:acl, area:domain, area:portal-self-service, area:infra, area:docs).
• Projects (Gitea's kanban-style project boards) visualise an iteration as a board: Todo / In progress / In review / Done.
• Issue templates live in .gitea/ISSUE_TEMPLATE/ with three forms: slice.md, bug.md, adr-proposal.md. The slice template encodes the Definition of Done from CLAUDE.md §3 as a checklist.
• Commits and PRs reference issues with #NN (e.g. feat(acl): default-fill bronorganisatie (refs #14)). Closing keywords on the merging commit (closes #14) move the issue to Done automatically.
• Pull Requests are the unit of code review. Trunk-based, squash-merged, with the PR description summarising the slice's acceptance.
• Releases are cut on tags via git-cliff-generated changelogs and published to Gitea Releases. Container images are tagged matching the release.

BACKLOG.md is regenerated (manually or by a small script) whenever a milestone is opened or closed. Treat it as a snapshot, not the source of truth.

12. Iteration shape — walking skeleton first

The first iteration is a walking skeleton that proves the spine end-to-end with minimal features. Each subsequent iteration is a vertical slice that adds one capability, deployable on its own. See BACKLOG.md for the slice list.

The skeleton: zorgprofessional logs in via mock DigiD → self-service portal submits a registration → BFF calls Domain Service → Domain Service starts a Flowable BPMN process and opens a zaak via the ACL → status event flows via NRC to the Event Subscriber → projection updated → openbaar register portal shows the entry.

Everything in the skeleton is real (no mocks beyond the IdP). Subsequent slices flesh out scenarios, edge cases, and the remaining portals/modules.

13. Definition of Done (per slice)

A slice is done when:

• Red → green → refactor commits visible in history (Conventional Commits).
• All CI gates pass on Gitea Actions (lint, unit, integration, mutation baseline, e2e for the slice's scenario, container build + push to Gitea Container Registry, compose-up smoke test).
• docker compose up from a fresh clone yields green health checks within 3 minutes.
• The Gherkin scenario(s) that define the slice pass.
• An ADR is added in docs/architecture/ if a non-obvious decision was made.
• The relevant runbook section is updated (in docs/runbooks/ or the Wiki, as appropriate per §10).
• A short demo note appended to docs/demo-script.md.
• The corresponding Gitea issue is closed via the merging commit's footer (closes #NN).

14. Open risks tracked

• OpenZaak version drift. Pin upstream image tags; document the upgrade procedure.
• Flowable + .NET integration friction. External-task worker pattern via REST; mitigate by isolating in Workflow Client.
• NL Design System completeness. Some components may need polyfills; record gaps in docs/frontend-decisions.md.
• NRC ordering and duplication. Event Subscriber must be idempotent; verified by acceptance tests that replay events.
• Gitea Actions ↔ GitHub Marketplace action drift. Some marketplace actions assume GitHub-specific APIs. Workflows pin actions to known-good versions; gaps are recorded in docs/runbooks/gitea-actions-gotchas.md.

15. Out of scope for v1

• OpenMetadata data governance module (v3 slice).
• Objecten as the authoritative register record store (v2 slice — v1 uses OpenZaak zaak-eigenschappen as a placeholder).
• Production-grade Helm chart (sketch only).
• Multi-tenancy.
• Real outbound notifications (email/SMS) — logged to console in v1.
• GitHub mirroring or any GitHub-hosted automation.