diff --git a/.gitignore b/.gitignore index 1499030..21f4674 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,10 @@ node_modules/ dist/ .angular/ +# Python / MkDocs +.venv/ +site/ + # OS .DS_Store Thumbs.db diff --git a/README.md b/README.md index ae79704..4f980e6 100644 --- a/README.md +++ b/README.md @@ -41,31 +41,32 @@ For the architecture rationale, see [docs/PRD.md §3](docs/PRD.md) and [docs/arc **Prerequisites** -- Docker Engine (or Docker Desktop) with Compose v2 -- ~8 GB free RAM, ~10 GB free disk -- Bash or PowerShell +- .NET 10 SDK (for `make lint/build/unit`) +- A container engine with Compose v2 — Docker, or rootless Podman (see [docs/runbooks/ci.md](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) -**Bring the stack up** +**Clone** ```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 +git clone git@git.labs.respellion.tech:eho/register-referentie.git +cd register-referentie ``` -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). +**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: -> **Wired today (Iteration 0):** only the placeholder BFF is in `infra/docker-compose.yml` so far. Bring it up and smoke-test its health endpoint: -> -> ```bash -> 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 this doubles as the compose-up smoke test. The remaining services and the URLs below land in later slices. +```bash +make ci # lint + build + unit + container smoke — the CI gate +``` -**Default URLs** +```bash +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 | |---|---| @@ -73,7 +74,7 @@ Health checks should be green within ~3 minutes on a developer machine. If somet | Openbaar register | http://localhost:4201 | | Behandel-portal | http://localhost:4202 | | Beheer-portal | http://localhost:4203 | -| BFF | http://localhost:5000 | +| BFF | http://localhost:8080 | | OpenZaak | http://localhost:8000 | | Open Notificaties | http://localhost:8001 | | Flowable | http://localhost:8080 | @@ -82,10 +83,12 @@ Health checks should be green within ~3 minutes on a developer machine. If somet Test credentials, BSNs, and personas: see [docs/synthetic-data.md](docs/synthetic-data.md). -**Re-seed synthetic data** +**Build the docs site** ```bash -./tools/seed.sh # or pwsh ./tools/seed.ps1 +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 ``` --- diff --git a/docs/architecture/adr-0001-loose-coupling.md b/docs/architecture/adr-0001-loose-coupling.md new file mode 100644 index 0000000..3354aef --- /dev/null +++ b/docs/architecture/adr-0001-loose-coupling.md @@ -0,0 +1,58 @@ +# ADR-0001: Loose coupling to upstream Common Ground modules + +- **Status:** Accepted +- **Date:** 2026-06-03 +- **Deciders:** Respellion engineering +- **Template note:** This is the first ADR and doubles as the worked example of + the Nygard template. Copy its shape for new ADRs (`adr-NNNN-title.md`). + +## Context + +This reference application orchestrates several upstream Common Ground modules — +OpenZaak (ZGW APIs), Open Notificaties (NRC), Objecten/Objecttypen, Flowable, +Keycloak. Each is an independently developed, independently deployed peer. The +temptation in a demo is to reach straight into a peer's database or couple to its +internal schema to move faster. That coupling is exactly what makes Common Ground +landscapes brittle and un-upgradeable in practice. + +We need a stance, recorded up front, on how our services may talk to these peers. + +## Decision + +**We integrate with upstream modules only through their documented public APIs, and +we isolate that integration behind explicit anti-corruption boundaries.** + +Concretely (mirrors CLAUDE.md §8): + +1. The **ACL** is the only code that talks to ZGW APIs; no other service constructs + ZGW URLs. +2. The **Workflow Client** is the only code that talks to Flowable; BPMN models hold + no OpenZaak knowledge. +3. **Portals talk only to the BFF** — never directly to a backend or a peer module. +4. **No direct database access across services or to any peer.** Each service owns + its schema; the Read Projection is a rebuildable derived artefact. +5. **Idempotency at every event boundary** (the Event Subscriber tolerates duplicate + and out-of-order NRC events). + +Bending any of these is an ADR-worthy moment (CLAUDE.md §14): stop and open an +`adr-proposal` issue first. + +## Consequences + +**Positive** + +- Upstream modules can be upgraded or swapped behind their APIs without rippling + through our services. +- Coupling is visible and minimal — anti-corruption code lives in one named place. +- The architecture teaches the Common Ground pattern by enforcing it. + +**Negative / costs** + +- More indirection: a translation layer (ACL, Workflow Client) instead of direct + calls. Accepted — it's the point. +- Eventual consistency across aggregates must be designed for, not assumed away. + +**Follow-up** + +- Each integration slice that touches a boundary references this ADR; new boundary + decisions get their own ADR. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5237204 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,23 @@ +# register-referentie + +A reference application demonstrating Respellion's Common Ground architecture +pattern. Quality and architectural clarity over feature throughput — every commit +should teach. + +## Where to go + +- **[Product Requirements](PRD.md)** — what we're building and why. +- **[ADR-0001: Loose coupling](architecture/adr-0001-loose-coupling.md)** — the + non-negotiable integration stance; the template for future ADRs. +- **[Working in Gitea](gitea-workflow.md)** — issues, milestones, branches, PRs. +- **[CI runbook](runbooks/ci.md)** — the pipeline and the `make ci` local gate. + +## Quickstart + +See the repository `README.md`. In short: clone, then either run the checks with +`make ci`, or bring the BFF up with +`docker compose -f infra/docker-compose.yml up -d --build --wait` and +`curl http://localhost:8080/health`. + +> This site is built with MkDocs Material (`mkdocs build`). It grows with the +> backlog; sections appear as their slices land. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..6f4e752 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,41 @@ +site_name: register-referentie +site_description: Reference application for Respellion's Common Ground architecture pattern +docs_dir: docs + +theme: + name: material + features: + - navigation.sections + - navigation.top + - content.code.copy + palette: + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + +nav: + - Home: index.md + - Product Requirements: PRD.md + - Architecture: + - "ADR-0001: Loose coupling": architecture/adr-0001-loose-coupling.md + - Working in Gitea: gitea-workflow.md + - Runbooks: + - CI: runbooks/ci.md + +markdown_extensions: + - admonition + - toc: + permalink: true + - pymdownx.superfences + +# Many docs referenced by PRD.md land in later slices; don't fail the build on them. +validation: + nav: + omitted_files: warn + links: + not_found: warn