What is the arc42 template, and what problem does its fixed section structure solve?
answer
- Template, not a method or notation
- 12 numbered sections, fixed meanings
- 5/6/7 = structure, behaviour, infrastructure
- §9 links to ADRs, §10 quality scenarios
- Empty section with a reason is allowed
basics
~20 sarc42 is a free, open template for architecture documentation: twelve fixed, numbered sections covering goals, constraints, context, solution strategy, building blocks, runtime, deployment, cross-cutting concepts, decisions, quality, risks, and glossary. Fixed slots mean readers always know where to look.
solid answer
~50 sarc42 (Starke & Hruschka) is a template — a set of twelve numbered sections with defined content — not a method or a notation. The sections are: 1 Introduction and Goals, 2 Constraints, 3 Context and Scope, 4 Solution Strategy, 5 Building Block View, 6 Runtime View, 7 Deployment View, 8 Cross-cutting Concepts, 9 Architecture Decisions, 10 Quality Requirements, 11 Risks and Technical Debt, 12 Glossary. Its value is *predictable structure*: every reader knows section 6 holds runtime scenarios and section 9 holds decisions, so nobody has to invent or discover an outline. Sections 5–7 mirror the three classic view types — static decomposition, dynamic behaviour, and infrastructure allocation. arc42 is explicitly notation-agnostic (UML, C4, boxes-and-lines all fit) and it is legitimate to leave a section empty with a note saying why. In practice teams keep it in Markdown or AsciiDoc in the repo, hyperlink section 9 to an ADR log, and put quality scenarios in section 10.
go deeper
Say arc42 is a free template of twelve fixed numbered sections, and name a few (context, building blocks, runtime, deployment, decisions) so readers always know where to look.
List the sections in groups, explain that 5/6/7 are static, dynamic and infrastructure views, and note that it is notation-agnostic and sections may be omitted with a reason.
Discuss how you would tailor it — a mandatory core of §1/§3/§4/§9, linking §9 to ADRs, generating §5/§7 diagrams — and the redundancy trap between §4, §8 and §9.
Frame it as an organisational convention: comparable documents across teams, review triggers tied to the template, how to keep it thin while still satisfying auditors and ISO/IEC/IEEE 42010-style expectations.
## What arc42 actually is **arc42** is a documentation *template* for software and system architectures, created by Gernot Starke and Peter Hruschka, published under a permissive licence. It is deliberately **not**: - a **method** (it does not tell you how to *do* architecture), - a **notation** (it does not require UML, C4, or any diagram language), - a **process gate** (it does not mandate sign-offs). It is a set of **twelve numbered sections with agreed meanings**, plus guidance on what belongs in each. Everything else — depth, notation, tooling, level of formality — is yours. ## The twelve sections | # | Section | What belongs there | |---|---------|--------------------| | 1 | Introduction and Goals | The functional essence, the top 3–5 **quality goals** (measurable properties like "p99 checkout < 300 ms"), and the stakeholder table (who reads this, what they care about). | | 2 | Constraints | Non-negotiables you did not choose: mandated cloud provider, regulatory rules, existing team skills, hardware, corporate standards. | | 3 | Context and Scope | The system as a black box plus every external partner — users, neighbouring systems, protocols, data flowing in/out. Both **business context** (domain-level) and **technical context** (channels, protocols). | | 4 | Solution Strategy | The handful of fundamental decisions, on one page: technology stack, decomposition style, how each top quality goal is achieved. The executive summary of the architecture. | | 5 | Building Block View | **Static decomposition**, hierarchical: level 1 = the whole system split into top parts; level 2 = zoom into one part; and so on. This is the "what code/modules exist" view. | | 6 | Runtime View | **Dynamic behaviour**: selected scenarios showing how building blocks collaborate over time — startup, a critical business transaction, error handling, shutdown. Sequence/activity diagrams or plain numbered steps. | | 7 | Deployment View | **Infrastructure allocation**: nodes, environments, networks, and which building blocks run where. | | 8 | Cross-cutting Concepts | Rules that recur everywhere and are not worth repeating per component: persistence approach, error handling, logging, i18n, security model, transaction strategy, domain model. | | 9 | Architecture Decisions | Significant decisions with rationale — usually just an index into an **ADR** (Architecture Decision Record) log. | | 10 | Quality Requirements | A **quality tree** plus concrete **quality scenarios** (stimulus → environment → response → measurable response value), refining section 1's goals. | | 11 | Risks and Technical Debt | Known risks, their impact, and planned mitigation; acknowledged debt. | | 12 | Glossary | Domain and technical terms with agreed definitions — the anti-ambiguity section. | A useful mnemonic for 5–7: **structure, behaviour, infrastructure**. ## Why fixed sections matter The expensive part of documentation is not writing — it is *finding*. When every project invents its own outline, each reader pays a discovery cost on every document. arc42 fixes the slots so: - **Readers navigate by number.** "Where's the deployment topology?" → section 7, always. - **Writers stop bikeshedding structure** and start filling content. - **Gaps become visible.** An empty section 10 loudly announces "we never wrote down our quality requirements", which an ad-hoc outline would hide. - **Cross-project comparison** becomes possible for reviewers and architects who read many systems. arc42 explicitly permits **omitting** sections: write "not applicable because …" rather than padding. That is the intended usage, not a violation. ## Trade-offs and criticisms - **Perceived heaviness.** Twelve sections looks like a book. The counter is that a good arc42 document can be 8–15 pages; the template scales down. Teams that produce 120-page arc42 documents have a *volume* problem, not a template problem. - **Redundancy risk.** Sections 4, 8 and 9 overlap if you are careless — solution strategy summarising, cross-cutting concepts detailing, decisions justifying. Discipline: strategy is one page, concepts are the recurring *how*, decisions are the *why with alternatives*. - **Not a replacement for diagrams-as-code or the C4 model.** C4 (Context, Container, Component, Code) is a *notation and zoom convention* that fits neatly inside arc42 sections 3 and 5. The two are commonly combined, not alternatives. - **Staleness.** A fixed template does nothing by itself to keep content current; that requires docs-as-code, generated diagrams and review triggers. ## How teams run it in practice - Keep it as Markdown/AsciiDoc **in the repository**, one file per section, rendered by a static site generator; review through pull requests. - Auto-generate what can be generated (module dependency diagrams, deployment topology from IaC) so sections 5 and 7 cannot drift. - Point section 9 at the ADR directory instead of duplicating decisions. - Treat sections 1, 3, 4 and 10 as the mandatory core; everything else grows on demand.
- How do the C4 model and arc42 relate — do you pick one?You use both. arc42 defines *which questions the document answers* and in what order; C4 defines *how you draw* the static structure at four zoom levels (System Context, Container, Component, Code). C4's Context diagram fits arc42 section 3, and its Container and Component diagrams are exactly the levels of arc42's section 5 Building Block View. C4 says nothing about constraints, quality scenarios, decisions or risks, which arc42 covers.
- Which arc42 sections would you insist on for a small service with two weeks of runway?Sections 1 (goals plus the top quality attributes), 3 (context and scope — the external interfaces are what other teams need), 4 (solution strategy on one page), and 9 (decisions, as an ADR log). Those four answer "what is it for, what does it touch, how is it built at a glance, and why". Building block, runtime and deployment views can start as a single diagram each and grow only when someone actually gets lost.
- What goes in arc42 section 8 (Cross-cutting Concepts) that shouldn't go in section 5?Section 5 describes *specific* building blocks and their responsibilities. Section 8 holds rules and patterns that apply across many of them — the persistence approach, the error-handling and logging conventions, the security model, the transaction strategy, the shared domain model. Putting them in section 8 avoids repeating the same paragraph inside every component description and gives you one place to change the rule.
arc42 is the standard floor plan of a supermarket chain: the aisles are always in the same order, so even in a store you've never entered you walk straight to the bread. The chain doesn't tell you what to stock — only where each kind of thing goes.
saying these in an interview costs you the question
- Calling arc42 a method or a process — it is only a template for the document's structure.
- Believing all twelve sections are mandatory and must be filled; omitting with a stated reason is intended usage.
- Thinking arc42 prescribes UML; it is deliberately notation-agnostic.
- Treating arc42 and C4 as competing choices rather than template plus notation.
- Duplicating decision rationale in section 4 instead of linking section 9 to the ADR log.
- Assuming a fixed template alone keeps documentation current — staleness needs generation and review triggers.