Init
This commit is contained in:
184
README.md
Normal file
184
README.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 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](BACKLOG.md) for the current iteration.
|
||||
|
||||
---
|
||||
|
||||
## Start here
|
||||
|
||||
| Document | Purpose |
|
||||
|---|---|
|
||||
| **[docs/PRD.md](docs/PRD.md)** | What we're building and why. Goals, non-goals, architecture summary, scope. Read once at project start. |
|
||||
| **[CLAUDE.md](CLAUDE.md)** | How we work. Engineering principles, TDD/DDD/BDD discipline, non-negotiable architectural rules, Gitea conventions. Read every task. |
|
||||
| **[BACKLOG.md](BACKLOG.md)** | Iteration plan. A curated mirror of the active Gitea milestone — Gitea Issues are the system of record. |
|
||||
| **[docs/architecture/](docs/architecture/)** | Diagrams (Mermaid sources) and ADRs. Start with `adr-0001-loose-coupling.md`. |
|
||||
| **[docs/runbooks/](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](docs/PRD.md) and [docs/architecture/](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**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
**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](docs/synthetic-data.md).
|
||||
|
||||
**Re-seed synthetic data**
|
||||
|
||||
```bash
|
||||
./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](docs/PRD.md).
|
||||
|
||||
---
|
||||
|
||||
## 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](CLAUDE.md).
|
||||
|
||||
**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](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:
|
||||
|
||||
```bash
|
||||
./tools/test-all.sh
|
||||
```
|
||||
|
||||
Run a focused slice (example):
|
||||
|
||||
```bash
|
||||
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](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](CLAUDE.md), **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](LICENSE). 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`.
|
||||
Reference in New Issue
Block a user