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

2.5 KiB

Raw Permalink Blame History

ADR-001: A register decision takes effect independently of case closure

Status

Accepted.

Context

case-framework (seam D, a stand-in for a maintained vendor case-management framework) refuses POST /cases/{id}/closure-request with 409 Conflict while any task on the case is still open. That rule belongs to the framework and is not ours to change — it is a conformist integration by design (seam D, New.Infrastructure.CaseFramework/CaseFrameworkGateway.cs).

The new domain's own rule is different: once an assessment (approve/reject) is recorded on a RegistrationApplication, that decision is legally in effect immediately. It cannot wait for an administrative task (e.g. a filing or notification step) to be ticked off in a separate system.

These two rules can genuinely conflict: an assessment can be recorded while a case-framework task is still open, at which point the case cannot yet be closed.

Decision

Recording an assessment and requesting case closure are treated as two separate, non-transactional steps:

POST /api/worklist/owned/{id}/assessment records the decision on the aggregate and commits it. This always succeeds if the domain invariants are satisfied, regardless of case-framework's task state.
The handler then calls POST /cases/{id}/closure-request on seam D as a best-effort follow-up. A 409 here is an expected, non-exceptional outcome, not a failure: the assessment is not rolled back, and the response reports closurePending: true instead of an error.

The user-facing consequence: the outcome is decided immediately, with the UI showing Besluit vastgelegd. Administratieve afsluiting in afwachting. when closure is still pending. Administrative closure catches up whenever the remaining task is completed — a scenario this demo does not automate, since it is not a claim about the framework, only proof that it can lag safely.

Consequences

The domain layer's assessment-recording method must not be coupled to case-framework's closure semantics — it has none of that knowledge, by design (New.Domain/New.Application never reference the case-framework client, see Architecture.Tests rules 1 and 8).
A case can sit in "decided but not administratively closed" indefinitely. That is accepted, not a bug: it is the visible cost of a conformist integration whose task-completion timing this system does not control.
No compensating transaction exists for a closure-request failure, because there is nothing to compensate — the assessment was correct and complete on its own terms.

2.5 KiB Raw Permalink Blame History