Skip to content

Architecture retrospective

Fifty PRs in, the repo carries a full retrospective of the principles that were actually used — with the evidence, the incidents, and the honest costs:

RETROSPECTIVE.md (repo — canonical)

What it covers, in brief:

  • Architecture principles as used — deny-by-default tenancy enforced by the negative-auth test registry, the contract-first registry + generated client, the three machine-enforced boundary walls (repositories, auth adapter, terminology resolver), and the ADR-013 mutation semantics everything else inherited. Each with where events tested it and whether it held.
  • Process principles — vertical slices, the uniform gate ladder, “cut features, not tests,” and docs-as-part-of-the-diff.
  • The stack scorecard — every major choice with why then, how it held up, and choose again?.
  • Clean-room discipline — what the ADR-001 boundary cost, what it bought, and when it’s warranted elsewhere (see also Clean-room rules).
  • Incidents → lessons — the turbo-cache masking, the E2E flake taxonomy (toast pinning, animation-vs-axe, Radix focus restoration), the staging symlink env resolution, and the PR-38 → PR-47 regression arc.

The forward-looking half — how to apply all of this to a new project — is the Project playbook.