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>
This commit is contained in:
@@ -7,7 +7,7 @@ Accepted.
|
||||
Seam B lets a user edit a **legacy-owned** case's applicant details (name,
|
||||
address, contact) from the new portal, without the new system taking
|
||||
ownership of that case. The legacy system remains the authority on this data
|
||||
until ownership is explicitly taken (§7.5).
|
||||
until ownership is explicitly taken ([ADR-003](ADR-003-ownership-is-taken-per-case.md)).
|
||||
|
||||
It is tempting, once a translation layer exists between the portal's request
|
||||
shape and legacy's `PUT /api/aanvragen/{id}/gegevens` shape, to also smuggle
|
||||
@@ -28,13 +28,14 @@ derived values, no defaulting. It only:
|
||||
(logged as a warning, never dropped or guessed at).
|
||||
|
||||
If a rule needs to be enforced on this data from the new portal, that is a
|
||||
signal the capability should be taken into ownership instead (§7.5), not
|
||||
signal the capability should be taken into ownership instead, not
|
||||
patched into the translator.
|
||||
|
||||
## Consequences
|
||||
- The portal cannot offer a better validation experience than legacy already
|
||||
has for this seam — by design. The `Gevalideerd door het legacy systeem`
|
||||
notice on the write-through form (§8.3) exists specifically so the user
|
||||
notice on the write-through form (`portal-frontend/src/app/case-detail/edit-applicant-details/`)
|
||||
exists specifically so the user
|
||||
knows why: this is the honest version of a seamless UI, not a limitation to
|
||||
hide.
|
||||
- Rule 11 in Architecture.Tests (no `New.Api` type both constructs a legacy
|
||||
|
||||
Reference in New Issue
Block a user