Solution Architecture Documentation
A practical solution architecture document template, C4 diagrams, arc42 structure and how much documentation is enough for different audiences.
Principles
Document for a purpose and an audience: decision-makers need context, options and risks; engineers need structure, interfaces and NFRs; operations need deployment and runbooks. Keep documents living, short and close to the code.
C4 model (Simon Brown)
| Level | Shows | Audience |
|---|---|---|
| 1. System context | The system, users and external systems | Everyone |
| 2. Container | Applications, databases, queues and how they communicate | Architects, developers, ops |
| 3. Component | Major components inside a container | Developers |
| 4. Code | Classes (rarely needed; generated) | Developers |
flowchart TB CUST[Customer<br/>person] --> SYS[Online banking system] STAFF[Bank staff] --> SYS SYS --> CORE[Core banking<br/>external system] SYS --> MAIL[Email provider<br/>external system] SYS --> IDP[Identity provider<br/>external system]
Solution architecture document template
- Executive summary and decision requested
- Business context, goals, scope and out of scope
- Requirements: key functional, NFRs with targets, constraints
- Assumptions, risks, dependencies
- Architecture overview (C4 context + container)
- Key design decisions (link ADRs) and alternatives
- Data architecture: entities, ownership, classification, flows, retention
- Integration: APIs, events, files, SLAs
- Security: identity, authorization, threat model summary, compliance
- Infrastructure and deployment: environments, regions, DR tier
- Operations: observability, SLOs, support model, runbooks
- Cost estimate and unit economics
- Migration/transition plan and roadmap
- Open questions
The arc42 template is a well-known alternative with similar sections.
Diagrams as code
Mermaid, PlantUML (C4-PlantUML), Structurizr DSL: versioned with the code, reviewable in pull requests, easy to update.
Interview questions and answers
How much documentation is enough?
Enough that a new engineer or reviewer understands the context, structure, key decisions and how to operate the system, without reading code first. Typically: context and container diagrams, ADRs, NFRs, interface catalog and runbooks; everything else on demand.