ehoandClaude Haiku 4.5
ddec15ccb2
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>
61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
# 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.
|