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:
eho
2026-08-01 09:15:39 +02:00
co-authored by Claude Haiku 4.5
parent 5f22156e6d
commit ddec15ccb2
10 changed files with 351 additions and 67 deletions
@@ -9,7 +9,7 @@ using Xunit;
namespace Architecture.Tests;
/// <summary>
/// Encodes §10's architecture rules as build-failing assertions. A demo that
/// Encodes the design's architecture rules as build-failing assertions. A demo that
/// passes the smoke script but fails these has demonstrated nothing - the
/// seam boundaries are the point, not an implementation detail.
/// </summary>
@@ -70,7 +70,7 @@ public class ArchitectureTests
[Fact]
public void Rule5_No_Legacy_Or_CaseFramework_Connection_String_In_New_Config()
{
// Config-file concern, not code - see §10. Verified by inspection: the
// Config-file concern, not code. Verified by inspection: the
// only connection string anywhere under New.* is ConnectionStrings:New
// (New.Infrastructure.Persistence.ServiceCollectionExtensions), and
// docker-compose.yml only ever injects ConnectionStrings__New into