Architecture & Technical Design · master area
System Architecture (C4 / arc42)
How services compose, where boundaries fall, what depends on what. Drawn at the level of detail the brief needs — and no more. The map a new dev reads in their first week and a Tech Lead points at in every Epic kickoff.
Owners: Tech Lead Phase it lives in: What We Build (Volume III) The corpus principle this enacts: Resolution, not maximum.
Where it lives in the chain
- What We Build · Technical Shaping — the canon
How to do this
The C4 model gives four levels, used at different times:
- Context — the system as a black box, with its users and external dependencies. One diagram for the product. Updated rarely.
- Containers — services, databases, queues, frontends. One diagram per product. Updated when services are added or removed.
- Components — inside one container. One diagram per service. Updated when a service is significantly refactored.
- Code — class-level. Almost never drawn manually. Generated if needed.
The discipline: draw the level the audience needs. A new dev needs Context and Containers. An Epic kickoff for a single service needs Components. Code-level diagrams are usually wasted effort.
What good practice looks like
The Context and Container diagrams live in the repo, as Mermaid or PlantUML, not as Confluence screenshots. They are updated by PR when the system changes — same review discipline as code. A diagram that doesn't match the running system is worse than no diagram, because it lies to readers who trust it.
The diagrams omit detail to be readable. A Container diagram with 40 boxes is unreadable; if there are 40 services, the diagram needs grouping (by domain, by team, by lifecycle). The chain's discipline is the same as for documents: enough to read, not enough to ship.
arc42 is an alternative framing — same idea, twelve sections instead of four levels. Use whichever fits the team's writing culture. Both are better than no map.
Related crafts
- Bounded Context Mapping — the conceptual cut
- Service Composition — the runtime cut
- Sequence Diagrams — the dynamic view