not
17f1f2f809
## What & why `docs/` is the source of truth (CLAUDE.md §12), but only pages listed in `mkdocs.yml`'s nav are published — and mkdocs' own `validation.nav.omitted_files: warn` keeps the build green while dropping the rest. So the site had quietly stopped at **ADR-0010** and **`runbooks/ci.md`**: 31 pages, including every ADR from 0011 to 0034, six of the seven runbooks, and `synthetic-data.md`, existed in the repo and nowhere else. - `infra/check-docs-nav.py` fails when a page under `docs/` is not in the nav. It runs in `make lint`, so the existing CI job gates it — python3 only, no new tooling, and no mkdocs install needed to check it. - The nav now lists all 34 ADRs, all 7 runbooks and `synthetic-data.md`. - ADR-0033's `Slice:` header said "none yet"; #25 closed it. - The landing page gained a pointer to the Talos runbook. Closes #169 ## Definition of Done - [x] Linked Gitea issue (above). - [x] Failing test committed before the fix — the red commit lists all 31 missing pages. - [x] Implementation makes the test pass. - [x] Conventional Commits referencing the issue (`refs #169`). - [ ] CI green — awaiting the run on this PR (`python3 infra/check-docs-nav.py` passes locally; `make lint` also needs the .NET SDK, which CI has). - [x] `docker compose up` unaffected — docs and `mkdocs.yml` only, plus one `make lint` line. - [x] Docs updated — that is the change. - [x] No ADR needed: no dependency, no boundary, no §8 rule touched. - [x] Not user-visible, so no demo note. ## Notes for reviewers - The check is a **substring test**, not a YAML parse (there's a `ponytail:` note in the script): a page's path either appears in `mkdocs.yml` or it doesn't. That keeps it dependency-free — `mkdocs.yml` can't be read by `yaml.safe_load` anyway, it carries a `!!python/name:` tag for the mermaid fence. It does not check that an entry *points at a file that exists*; mkdocs' `not_found: warn` covers that direction. - ADR labels in the nav are shortened by hand (`"ADR-0013: Behandel-portal wiring"`), since several H1s are a full sentence. **Known gap, not fixed here:** CLAUDE.md §12 says the site is "published via a Gitea Actions workflow to Gitea Pages", and no such workflow exists — `mkdocs build` is never run, by CI or by any make target. Gitea has no built-in Pages, so publishing needs a decision (a `gitea-pages` server, an artifact, or a static host) rather than a patch. Worth its own issue if the published site is actually wanted; until then this PR makes the nav correct for whoever runs `mkdocs serve`.Reviewed-on: #172
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
- .NET 10 SDK (for
make lint/build/unit) - A container engine with Compose v2 — Docker, or rootless Podman (see 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)
Clone
git clone git@git.labs.respellion.tech:eho/register-referentie.git
cd register-referentie
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:
make ci # lint + build + unit + container smoke — the CI gate
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 |
|---|---|
| Self-Service portal | http://localhost:4200 |
| Openbaar register | http://localhost:4201 |
| Behandel-portal | http://localhost:4202 |
| Beheer-portal | http://localhost:4203 |
| BFF | http://localhost:8080 |
| 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.
Build the docs site
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
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
- Find or open a Gitea issue using one of the templates in
.gitea/ISSUE_TEMPLATE/(slice.md,bug.md,adr-proposal.md). - Assign yourself, move it to "In progress" on the milestone's project board.
- Branch off
main, follow the CLAUDE.md working agreements (TDD: red commit → green commit → refactor commit). - Open a PR using the template, link the issue, ensure the Gitea Actions pipeline is green.
- 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-proposalissue. - Anything sensitive: contact Respellion through the channel in
docs/runbooks/contact.md.