Introduction & Goals
Requirements, quality goals, and the stakeholders who care.
structure for architecture docs
arc42 & Docs-as-Code
Plain text and Git tell you how to document. arc42 tells you what to write. Together they turn architecture documentation from a blank page into a reviewable, buildable artifact.
arc42 is a free, proven template for documenting software architectures, created by Dr. Gernot Starke and Dr. Peter Hruschka. It gives you twelve clear sections — enough structure to be useful, light enough to stay out of the way. You fill only what your project needs and delete the rest.
arc42 answers “what goes in architecture documentation?” so you can spend your energy on the answers, not the outline.
Because the template ships as plain text — AsciiDoc and Markdown among others — it drops straight into a Docs-as-Code workflow. The architecture lives in Git next to the code, every change is reviewed in a pull request, and the build renders it to HTML or PDF on every commit.
the template
01
02
03
04
05
06
07
08
09
10
11
12
Twelve sections, no blank page
A complete map of an architecture — from goals to glossary.
Constraints
The technical and organisational boundaries you must work within.
Context & Scope
The system’s neighbours and the interfaces it exposes.
Solution Strategy
The fundamental decisions that shape the whole architecture.
Building Block View
The static decomposition into components and their responsibilities.
Runtime View
How the building blocks collaborate in key scenarios.
Deployment View
The technical infrastructure and how software maps onto it.
Crosscutting Concepts
Patterns and rules that apply across the system.
Architecture Decisions
The important choices, captured with their rationale (ADRs).
Quality Requirements
A quality tree and concrete, testable quality scenarios.
Risks & Technical Debt
Known risks and debt, made visible instead of forgotten.
Glossary
Shared vocabulary, so everyone means the same thing.
why it pairs with docs-as-code
Structure meets workflow
- Plain-text templates — AsciiDoc & Markdown, ready for Git
- Diagrams as text — PlantUML and C4 fit each section
- Decisions as ADRs — reviewed like code, in pull requests
- Built on CI — rendered to HTML or PDF on every commit
- Free and open — no licence, no lock-in
start with structure
Scaffold arc42 in one command.
docToolchain ships the arc42 templates and can download a ready-to-fill copy into your project — AsciiDoc, diagrams, and build included.