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

  1. Executive summary and decision requested
  2. Business context, goals, scope and out of scope
  3. Requirements: key functional, NFRs with targets, constraints
  4. Assumptions, risks, dependencies
  5. Architecture overview (C4 context + container)
  6. Key design decisions (link ADRs) and alternatives
  7. Data architecture: entities, ownership, classification, flows, retention
  8. Integration: APIs, events, files, SLAs
  9. Security: identity, authorization, threat model summary, compliance
  10. Infrastructure and deployment: environments, regions, DR tier
  11. Operations: observability, SLOs, support model, runbooks
  12. Cost estimate and unit economics
  13. Migration/transition plan and roadmap
  14. 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.