register-reference

A reference application demonstrating how to build a Dutch government register (a BIG-style professional register) on top of unforked Common Ground modules — OpenZaak, Open Notificaties, Objecten, Open Klant — with loose coupling, modern workflow tooling, and data-governance ready integration points.

This repository is the runnable companion to Respellion's Foundations playbook entry on Common Ground architecture for non-municipal contexts (CIBG, DUO, RVO, and similar uitvoeringsorganisaties).

Status: under active development. See BACKLOG.md for the current iteration.

---

Start here

Document	Purpose
docs/PRD.md	What we're building and why. Goals, non-goals, architecture summary, scope. Read once at project start.
CLAUDE.md	How we work. Engineering principles, TDD/DDD/BDD discipline, non-negotiable architectural rules, Gitea conventions. Read every task.
BACKLOG.md	Iteration plan. A curated mirror of the active Gitea milestone — Gitea Issues are the system of record.
docs/architecture/	Diagrams (Mermaid sources) and ADRs. Start with adr-0001-loose-coupling.md.
docs/runbooks/	Operational guides: local startup, seeding, common failures, CI debugging.

The day-to-day operational pages — environment URLs, known issues right now, on-call notes — live in the Gitea Wiki for this repository. The wiki points at docs/ for anything authoritative.

---

What this application demonstrates

• A BIG-style professional register modelled on Dutch public-sector patterns, with four end-user portals: self-service, openbaar register, behandel-portal, beheer-portal.
• Common Ground modules as upstream peers — never forked, reached only via documented APIs (ZGW, NRC events).
• An Anti-Corruption Layer that confines all ZGW knowledge to one place, so the rest of the codebase stays domain-shaped rather than municipality-shaped.
• BPMN + DMN workflows via Flowable as a separate, swappable module — using the external-task job-worker pattern so BPMN models never reach into OpenZaak.
• A read projection as the public-facing data path, decoupled from the authoritative modules.
• Synthetic data and mock identity (Keycloak realms standing in for DigiD, eHerkenning, eIDAS, and a medewerker IdP) so the whole system runs locally without external dependencies.
• TDD, DDD, BDD, mutation testing, ADRs, and Conventional Commits as enforced defaults — encoded in CI.
• Gitea-native delivery: source, issues, milestones, project boards, releases, container registry, packages, wiki, and Actions.

For the architecture rationale, see docs/PRD.md §3 and docs/architecture/.

---

Local quickstart

Prerequisites

• Docker Engine (or Docker Desktop) with Compose v2
• ~8 GB free RAM, ~10 GB free disk
• Bash or PowerShell

Bring the stack up

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

Health checks should be green within ~3 minutes on a developer machine. If something fails, see docs/runbooks/local-startup.md.

Default URLs

Service	URL
Self-Service portal	http://localhost:4200
Openbaar register	http://localhost:4201
Behandel-portal	http://localhost:4202
Beheer-portal	http://localhost:4203
BFF	http://localhost:5000
OpenZaak	http://localhost:8000
Open Notificaties	http://localhost:8001
Flowable	http://localhost:8080
Keycloak	http://localhost:8180
MkDocs site (after build)	http://localhost:8000/docs/

Test credentials, BSNs, and personas: see docs/synthetic-data.md.

Re-seed synthetic data

./tools/seed.sh               # or pwsh ./tools/seed.ps1

---

Repository layout

register-reference/
├── apps/                       # Angular portals (Nx monorepo)
│   ├── self-service/
│   ├── openbaar/
│   ├── behandel/
│   └── beheer/
├── libs/                       # shared Angular libs (UI, auth, generated API client)
├── services/                   # .NET services
│   ├── bff/
│   ├── domain/                 # BIG Domain Service
│   ├── acl/                    # Anti-Corruption Layer (the only code that knows ZGW)
│   ├── event-subscriber/
│   └── projection-api/
├── workflows/                  # BPMN + DMN sources
├── infra/                      # docker-compose, Keycloak, OpenZaak, Flowable, seed
├── tests/
│   ├── acceptance/             # Gherkin / Reqnroll BDD scenarios
│   └── e2e/                    # Playwright
├── docs/                       # versioned documentation (MkDocs source)
├── .gitea/                     # Gitea Actions workflows, issue/PR templates
├── CLAUDE.md                   # working agreements
├── BACKLOG.md                  # iteration plan (mirror of active milestone)
└── README.md

Full description in docs/PRD.md §9.

---

Working in this repository

Source of truth for work: Gitea Issues + Milestones for this repository. BACKLOG.md is a mirror.

Branching: trunk-based. Short-lived branches off main, named <type>/<issue-number>-<short-slug> (e.g. feat/14-acl-default-fill).

Commits: Conventional Commits, referencing the Gitea issue:

feat(acl): default-fill bronorganisatie (refs #14)

The merging PR closes the issue via closes #14 in the squash-commit body.

Pull Requests: the unit of review. Squash-merged. PR template enforces the Definition of Done checklist from CLAUDE.md §3.

Releases: CalVer (YYYY.MM.PATCH), tagged on main, changelog generated by git-cliff, published as a Gitea Release with container images in the Gitea Container Registry.

See CLAUDE.md for the full working agreements, the architectural non-negotiables, and the rules Claude Code follows on every task.

---

Testing

• Unit tests — dominant. .NET (xUnit) and Angular (Vitest / Testing Library).
• Integration tests — Testcontainers-driven, exercising real OpenZaak, Flowable, NRC.
• Acceptance tests — Gherkin scenarios in tests/acceptance/, one per user-visible flow.
• End-to-end — Playwright, expanding slice by slice from the walking-skeleton happy path.
• Mutation testing — Stryker.NET and Stryker, baseline-ratcheted on main.

Run everything:

./tools/test-all.sh

Run a focused slice (example):

dotnet test services/acl

---

Contributing

1. Find or open a Gitea issue using one of the templates in .gitea/ISSUE_TEMPLATE/ (slice.md, bug.md, adr-proposal.md).
2. Assign yourself, move it to "In progress" on the milestone's project board.
3. Branch off main, follow the CLAUDE.md working agreements (TDD: red commit → green commit → refactor commit).
4. Open a PR using the template, link the issue, ensure the Gitea Actions pipeline is green.
5. Squash-merge once approved. The merging commit closes the issue.

If a task pushes against any of the architectural rules in CLAUDE.md §8, stop and open an adr-proposal issue first. That conversation is more important than the code.

---

License and attribution

Respellion-authored code is licensed under EUPL-1.2. Upstream Common Ground modules retain their own licences (typically EUPL-1.2 or MIT — see each module's repository).

This reference application is not an official product of CIBG, DUO, VNG Realisatie, or any government body. It is a Respellion playbook artefact illustrating an architectural pattern.

---

Contact

• Issues, questions, proposals: open a Gitea issue on this repository.
• Architectural discussion: start with an adr-proposal issue.
• Anything sensitive: contact Respellion through the channel in docs/runbooks/contact.md.