Architecture Standard — Decisions & Service Boundaries¶

v1.0 — 2026-06-06 — added from expert review (items 1, 10, 11: Milanović, Nygard, Newman).

Architecture Decision Records (ADRs)¶

Every significant architectural decision is recorded as an ADR in the repo it affects, under docs/adr/NNNN-short-title.md; org-wide decisions live in the ExpertGroup.DevelopmentGuidance repo under adr/.
Format: the Nygard template (see templates/ADR-template.md) — Status / Context / Decision / Consequences, one file per decision, kept short (a page or less).
ADRs are immutable once accepted: to change course, write a new ADR that supersedes the old one (set old Status to "Superseded by ADR-NNNN").
What counts as significant: anything you'd have to explain to a new developer or that is expensive to reverse — framework/library choices, service boundaries, data ownership, protocol choices, deviations from these standards.
The DECISION items ratified in these standards are org-level ADRs; ADR-001 (environment-branch model) is the first.

Every active service keeps C4 diagrams as code in the repo under docs/diagrams/: at minimum a Context diagram (the service among its neighbors) and a Container diagram (its deployable pieces and data stores). Component-level diagrams only where they earn their upkeep.
Format: Mermaid (renders natively in Azure DevOps and VS Code — no extra tooling); Structurizr DSL acceptable where a team already uses it.
Diagrams are updated in the same PR that changes the architecture they describe — a diagram that can drift is worse than no diagram. Claude sessions can generate and maintain these; reviewers just check they match the change.
Legacy/frozen repos are exempt.

Independent deployability is the acid test: any service must be deployable to production without coordinating other teams or services. If two services must always ship together, they are one service.
No shared databases between services — ever. Each service owns its schema; others integrate via its GraphQL/REST API or domain messages (ExpertGroup.Core.Ipc / RabbitMQ), never by reading its tables.
One team owns a service end-to-end: build, deploy, operate.
Align service boundaries to business domains, not technical layers.