Files

T

ehoandClaude Haiku 4.5 ddec15ccb2 docs(architecture): add diagrams and implementation playbook

Added three new documents with nine Mermaid diagrams to make the strangler
fig strategy visible:

- README: container topology diagram at the start, with the proxy entry point
  and three seams labelled
- docs/architecture.md: five diagrams tracing the exact implementation:
  - The four seams and who holds authority at each boundary
  - How by-id read goes through the resolver, but list-read bypasses it
  - Case lifecycle state machine (the strategy in one picture)
  - Take-ownership sequence with failure windows annotated
  - Write-through error round-trip showing zero validation logic crossed
- docs/playbook.md: how to apply this to a production system:
  - Write-path decision tree (five read/write patterns)
  - Cutover ordering diagram (side-effects-free first, least recoverable last)
  - Seven transferable rules with pointers to the files that demonstrate them
  - Scope diagram of what's proven vs. left as your decisions

Resolved all 13 dangling § citations (to an absent spec doc) by linking to
the actual files or dropping them. Replaced portal-frontend/README.md
boilerplate with accurate content. All diagrams parse and link-check clean.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

2026-08-01 09:15:39 +02:00

3.2 KiB

Raw Permalink Blame History

ADR-003: Ownership is taken per case for now — bulk migration is a later, separate capability

Status

Accepted (interim). Superseded in part once bulk migration tooling (see "Future work" below) ships.

Context

The end state for at least some processes — registration cases among them — is a bulk cutover: migrate the whole remaining population in one operation and retire the legacy path for that process on a clean date. That is a real, wanted outcome, not something this design argues against.

What this system cannot do is wait for that bulk-migration tooling to exist before shipping anything of business value. Building a safe bulk migration requires solving problems this demo deliberately defers: what happens to rows that fail adoption (four such failure modes already exist in the seed data — contact, BSN, motivation, and partial-address invariant violations), how a partially-failed batch is reported and retried, and how the cutover is scheduled and communicated. None of that should block getting the read ACL, write-through ACL, and take-ownership mechanics themselves live and earning their keep.

Decision

Ship now with ownership taken one legacy case at a time, via POST /api/worklist/legacy/{aanvraagId}/take-ownership, triggered by an explicit user action in the portal. This is the interim mechanism, not the final one for every process.

This is deliberately the right building block either way:

It is the same adoption logic (mapping, invariant validation, case-framework correlation, atomic persistence, migratie-vlag flip) that a future bulk tool would need to call in a loop — building it per-case first means the bulk tool is an orchestration layer on top of already-proven logic, not a parallel implementation to keep in sync.
It gives a real, visible answer today for what a bulk migration would otherwise discover the hard way: which legacy rows fail adoption and why (surfaced here as a named 422 per case, not a batch-job log line).
The read ACL (seam A) and write-through ACL (seam B) must work correctly for a partially-adopted population regardless of how adoption happens — that requirement doesn't change once bulk tooling exists.

Consequences

Until bulk tooling exists, full legacy retirement for a process happens case-by-case, which is slower than a scheduled cutover — accepted as the cost of shipping the seam mechanics now rather than waiting.
Reversal (ReleaseOwnershipHandler) stays per-case and gated on domain_writes_since for the same reason a bulk reversal would be unsafe absent a sync (docs/sync-not-implemented.md): undoing adoption after edits would silently discard them.
This demo's non-goals (README, "Deliberate substitutions and omissions") exclude building the bulk migration tool itself — that's future work, not a rejected idea.

Future work

A bulk migration tool for a given process (e.g. registration cases) can reuse the same take-ownership handler per legacy id, adding: pre-flight reporting of which rows would fail adoption and why (so the four invariant-failure classes seen here are triaged before cutover, not discovered during it), a scheduled cutover window, and a decision on whether failed rows block the cutover or are carved out and finished by hand.

3.2 KiB Raw Permalink Blame History