Leer en español · Lire en français · Auf Deutsch lesen

Section 4.6 of 4.8 · Intermediate · 20 min read

arc42 and other documentation templates

Video lesson

5 min · narrated, with captions

Listen only (audio)

Read the transcript

Once you know what to document, you need somewhere to put it. In this lesson you'll learn arc forty-two, a widely used, free template for architecture descriptions, and how to use it lightly.

Think of a car's handbook. Every manual has a section on tyres, one on warning lights, and one on servicing. So you know where to look, whichever car you're in. A documentation template does the same for software architecture. And you don't have to fill every section. A small system might need only four or five short ones.

Arc forty-two is a free template, created by Gernot Starke and Peter Hruschka and used in practice since 2005. It's published under a Creative Commons licence, and is especially widespread in German-speaking countries. It is deliberately not a method and not a notation. It doesn't tell you how to design, or which diagram style to use. It's a set of twelve labelled drawers: for each kind of information, it says where to put it.

Here are the twelve sections, grouped by the question they answer. Sections one to three set the goals and boundaries: what the system is for, what limits the solution, and where the system ends. Section four, the solution strategy, states the few fundamental ideas that shape everything else. Sections eight and nine hold the cross-cutting concepts and decisions that apply across the solution. Decision records belong in section nine. Sections five to seven show the structure from three angles: the building blocks, how they cooperate at runtime, and where they are deployed. And sections ten to twelve make quality requirements, risks and technical debt, and vocabulary explicit. The shaded sections are the core of even a minimal description: goals, context, strategy and the top-level building blocks. The arc forty-two guidance adds three to five quality scenarios and the key concepts.

The most common way to fail with arc forty-two is to treat it as a form: twelve headings, each filled with something, and a result that's long, generic and never read. Its own guidance says every section is optional. If a section isn't needed, say so in one line, so readers know the gap is intentional. Link rather than copy. Requirements live in the backlog, decisions in the decision record folder, and deployment in the infrastructure code. Copies drift out of step. And prefer diagrams with short tables to pages of prose. It pairs well with C4: a context diagram in section three, and a container diagram as the first level of building blocks in section five.

Here's a one-page arc forty-two lite description of the food-delivery platform. Section one lists the quality goals in priority order. First, no order is lost or charged twice. Second, fast confirmation at peak. The constraints are short: card data never touches the platform's systems, and personal data stays in EU regions. The solution strategy ties each fundamental choice to a goal, such as asynchronous order events through a managed broker, and cites the decision record. The building blocks are the C4 container diagram, with a second level only for ordering, the riskiest service. Deployment simply points to the infrastructure repository, which is the source of truth. The decisions section lists the must-read records, and risks have owners. Nothing is copied, so nothing can drift. And a reader can trace each major choice back to a goal.

Other templates exist. The Software Engineering Institute's Views and Beyond template is more thorough, documenting every view the same way, with an explicit mapping between views. It suits large, long-lived or contractually specified systems. IEEE 1016 specifies software design descriptions, used in defence and aerospace contracts. It sits closer to detailed design, and has been inactive since 2020, though it's still cited. The standard from Section four point two, ISO/IEC/IEEE 42010, doesn't prescribe any template. It asks for content: stakeholders, concerns, viewpoints, views, correspondences and rationale. Plain arc forty-two often lacks an explicit link from each concern to its view, but the gaps are small. A short viewpoint table and some mapping tables close them.

Watch for three mistakes. Filling every section because it exists: one line explaining why a section is empty beats a page of filler. A building block view with dozens of boxes at the first level. It should fit on one screen. And writing the description once and never again. Keep it under version control, review it with significant changes, and show a last reviewed date.

The full section sets out what goes in each of the twelve sections, for small and large systems. Next, in Section four point seven, we tackle the problem that defeats most documentation: going stale. See you there.

What you need to know

arc42, created by Gernot Starke and Peter Hruschka and free under a Creative Commons licence, is a template of twelve sections; it prescribes where information goes, not how to design or which notation to use.
The sections are introduction and goals, constraints, context and scope, solution strategy, building block view, runtime view, deployment view, cross-cutting concepts, architecture decisions, quality requirements, risks and technical debt, and glossary.
Every section is optional; a minimal description covers three to five quality scenarios, the context, a brief solution strategy, the level-1 building block view and the key cross-cutting concepts.
Use arc42 lightly: link to requirements, ADRs and infrastructure code rather than copying them, and state deliberately when a section is not needed.
The SEI Views and Beyond template is more thorough, with a roadmap, per-view packages and a mapping between views; IEEE 1016-2009 specifies software design descriptions and has been inactive-reserved since 2020.
ISO/IEC/IEEE 42010 prescribes the content of an architecture description, not a template; an arc42 description conforms once stakeholders, concerns, viewpoints, views, correspondences and rationale are made explicit.

What arc42 is

arc42 is a free template for describing and communicating software architecture, created by Gernot Starke and Peter Hruschka and used in practice since 2005. It is published under a Creative Commons Attribution-ShareAlike licence, in more than a dozen languages and in formats including AsciiDoc, Markdown and Word, with a plain version and a version with built-in help text. It is especially widespread in German-speaking countries and in iSAQB training, but it is used worldwide.

arc42 is deliberately not a method and not a notation. It does not tell you how to design, and it does not prescribe UML, C4 or any other diagram style. It is a set of twelve labelled drawers: for each kind of architectural information, it says where to put it, so that every reader knows where to look and every writer knows what is missing. Its authors are explicit that every section is optional; a small system might fill four sections in a few pages, a large one might fill all twelve across many.

The template builds on ideas from earlier in this chapter. Its three views (building block, runtime and deployment) correspond closely to the SEI's module, component-and-connector and allocation categories and to Kruchten's development, process and physical views from views and viewpoints. Its decision section is where Architecture Decision Records go, and its quality section is where the quality attribute scenarios of Chapter 2 go.

The twelve sections

The diagram groups the sections by the question they answer. Sections 1 to 3 set the goals and boundaries: what the system is for, what limits the solution and where the system ends. Section 4 states the solution's fundamental ideas, and sections 8 and 9 hold the principles and decisions that apply across it. Sections 5 to 7 show the structure from three angles. Sections 10 to 12 make quality, risk and vocabulary explicit.

The structure of arc42

The twelve arc42 sections grouped by purpose; the highlighted sections are the core of even a minimal description.

What goes in each section, and how much

Section	What goes in it	Small system (one team)	Large system (many teams)
1. Introduction and goals	A short requirements overview, the top three to five quality goals in priority order, and a stakeholder table with each group's expectations.	Half a page: purpose, three quality goals, five or six stakeholders.	Two or three pages, linking to the requirements documents rather than copying them.
2. Constraints	Anything that limits design freedom: regulations, mandated technologies, organisational rules, deadlines, budget, conventions.	A bullet list.	A table grouped into technical, organisational and legal constraints, each with its source.
3. Context and scope	The system as a black box: users and neighbouring systems, what flows between them (business context) and the channels and protocols used (technical context).	One context diagram (often a C4 system context diagram) and a short table of external interfaces.	Business and technical context diagrams plus an interface table with owners and contracts.
4. Solution strategy	The few fundamental decisions and approaches that shape everything else: decomposition style, key technologies, how the top quality goals are achieved.	A handful of bullets, each tied to a quality goal.	One or two pages; a table mapping each quality goal to the approach that serves it.
5. Building block view	The static decomposition into building blocks (subsystems, services, components, modules), refined level by level, each with responsibilities and interfaces. Usually the largest section.	Level 1 only: one diagram (a C4 container diagram works) and a sentence per block.	Level 1 for the whole system, levels 2 and 3 only for complex or risky parts.
6. Runtime view	How building blocks cooperate in important scenarios: key use cases, start-up, error handling, failover.	One or two sequence diagrams for the most important flows.	The critical and the surprising scenarios; never every use case.
7. Deployment view	The technical infrastructure: environments, nodes, networks, and which building blocks run where.	One diagram or a short list of hosted services.	Diagrams per environment and region, linked to the infrastructure-as-code that defines them.
8. Cross-cutting concepts	Concepts that apply across many building blocks: domain model, security, error handling, logging and observability, persistence, internationalisation, testing.	A short paragraph each for the two or three concepts that matter.	A page or more per concept, often owned by a platform or enabling team.
9. Architecture decisions	Important decisions with their reasons, unless recorded elsewhere.	A link to the ADR folder.	A link to the decision log, perhaps with the five or six decisions every newcomer must know.
10. Quality requirements	A quality tree (the utility tree from Chapter 2) and concrete quality scenarios that refine the quality goals of section 1.	Three to five scenarios.	A utility tree with prioritised scenarios, linked to fitness functions.
11. Risks and technical debt	Known technical risks and debt, ideally prioritised, with mitigation plans.	A short list, reviewed each quarter.	A link to the debt register, plus the top risks with owners.
12. Glossary	The important domain and technical terms, with definitions everyone agrees on.	Ten or so terms.	A shared glossary, sometimes per bounded context.

Using arc42 lightly

The most common way to fail with arc42 is to treat it as a form that must be completed: twelve headings are created, each is filled with something, and the result is long, generic and never read. The template's own guidance points the other way. The arc42 FAQ says there is no general rule for the minimum, because it depends on criticality, size, complexity and risk, but suggests that even a minimal description should contain three to five central quality requirements as scenarios, the context and external interfaces, a brief solution strategy, the level-1 building block view and the most important cross-cutting concepts.

Four habits keep arc42 light. Delete empty sections or mark them deliberately (Deployment: single managed platform; see the infrastructure repository), so that a reader knows the gap is intentional. Link rather than copy: the requirements live in the backlog, the decisions in the ADR folder, the deployment in infrastructure-as-code; arc42 points to them. Prefer diagrams with short element tables to pages of prose. Write for the next reader's questions, not for completeness: if nobody will ask about the runtime behaviour of the admin screens, do not describe it.

arc42 combines well with the C4 model. A common pairing is a C4 system context diagram in section 3, a container diagram as level 1 of the building block view in section 5 with component diagrams as level 2, and a C4 deployment diagram in section 7. Kept as diagrams as code in the same repository as the arc42 text, the whole description can be versioned and reviewed like code.

If you are new to this

Step by step: a pointer, not a copy

This section's hardest idea is that arc42 is a set of labelled drawers, not a form to fill in. Many sections should hold a short pointer to where the real information already lives, not a copy of it.

The food-delivery team already keeps two C4 diagrams (system context and containers), a decision log in docs/decisions and its quality scenarios in docs/quality.md. It now organises them with arc42.
The diagrams go into their drawers: the context diagram in section 3, and the container diagram as level 1 of the building block view in section 5.
For section 9, architecture decisions, someone suggests pasting in the full text of every decision record, so that everything sits in one document.
Then ADR-0015 supersedes ADR-0009, as in the previous section. The pull request that adds ADR-0015 also changes the decision log, but nobody remembers the pasted copy, which still presents ADR-0009 as accepted.
A reader now finds two answers: the arc42 description says push notifications go through a third-party SDK, while the decision log says the team runs its own notification service. They cannot tell which is true, and begin to distrust the whole description.
So section 9 holds a link to docs/decisions and the numbers of a few must-read records. Every other section works the same way: the quality scenarios stay in docs/quality.md, the deployment in the infrastructure repository, and a section with nothing to add is deleted or says why in one line.
The lesson: arc42 tells readers where to look; it does not have to hold everything itself. Give each fact one home and let the template point to it, and the description stays short and true.

Worked example: arc42-lite for the food-delivery platform

The page below is a complete arc42-lite description of the food-delivery platform used throughout this chapter. It fits on one printed page plus the context diagram, yet it answers the questions a new engineer, an operations lead or an auditor would ask first, and it points to where the detail lives.

Section 3: business context

The context of the platform: three groups of users on the left, three external services on the right, each arrow labelled with what is exchanged; channels and protocols belong in the technical context.

Worked example

Worked example: a one-page arc42-lite description

Food-delivery platform, architecture description, version reviewed 2026-10-01 by the principal architect. Sections that would add nothing are stated as such rather than left empty.

1. Goals	Let customers order from local restaurants and track delivery in real time. Quality goals in priority order: (1) no order is lost or charged twice; (2) order confirmation p99 under 1.5 s at 120 orders/s; (3) a new consumer of order data can be added without changing the ordering service. Stakeholders: customers, restaurants, couriers, operations, finance, the data protection officer, the payment provider.
2. Constraints	Card data never touches our systems (hosted card fields from the payment provider, to limit PCI DSS scope). UK and EU personal data stays in EU regions. Five squads; server-side code in Java, Go or TypeScript only.
3. Context	See the context diagram. External interfaces: payment provider REST API and webhooks; APNs and FCM for push; maps provider for routes and ETAs. Interface owners and contracts are listed in `docs/interfaces.md`.
4. Solution strategy	Separate services for ordering, dispatch and notifications (goal 3); asynchronous order events through a managed broker with a transactional outbox (goals 1 and 2, ADR-0012); managed PostgreSQL for orders (goal 1, ADR-0007); idempotency keys on every payment call (goal 1).
5. Building blocks	Level 1 is the C4 container diagram in `docs/diagrams/containers.dsl`: three client apps, API gateway, ordering, dispatch and notification services, order database and the order events topic on the managed broker. Level 2 exists only for ordering, the riskiest service.
6. Runtime	Two scenarios: place and pay for an order (sequence diagram) and payment provider timeout (shows the retry with idempotency key and the pending state).
7. Deployment	One cloud provider, two EU regions, managed Kubernetes and managed databases; defined in the infrastructure repository, which is the source of truth.
8. Concepts	Domain model (order lifecycle states); idempotency and retries; observability (trace IDs carried in every event); personal data handling and retention.
9. Decisions	See the decision log in `docs/decisions/`. Must-read records: ADR-0004, ADR-0007, ADR-0012.
10. Quality	Scenarios QS-1 to QS-5 in `docs/quality.md`, each with a response measure; QS-3 (confirmation latency) and QS-1 (no lost orders) have automated fitness functions.
11. Risks and debt	Single broker vendor (lock-in, accepted in ADR-0012); dispatch still reads the order database directly (debt, removal planned for Q1); maps provider rate limits at peak (risk, owner: dispatch squad).
12. Glossary	Order, basket, acceptance, pickup, drop-off, dispatch, ETA, outbox, idempotency key: defined in `docs/glossary.md`.

Every section is either filled briefly or points to a single source of truth; nothing is copied, so nothing can drift out of step.

The quality goals in section 1 drive the strategy in section 4, which cites the decisions in section 9: a reader can trace each major choice back to a goal.

Other templates

The SEI Views and Beyond template. The Software Engineering Institute publishes a documentation template that follows Documenting Software Architectures: Views and Beyond by Paul Clements and colleagues. Its top level has six parts: a documentation roadmap and overview, architecture background, the views, the mapping between views, referenced materials, and a glossary with acronyms. Each view is documented in the same way, with a primary presentation, an element catalogue, a context diagram, a variability guide and the rationale (described in the "Going deeper" box of Section 4.2). It is more thorough than arc42 and suits large, long-lived or contractually specified systems where every view must be complete and cross-referenced; its mapping between views is a strength that arc42 leaves implicit.

IEEE 1016. IEEE Std 1016-2009, Software Design Descriptions, specifies the content and organisation of a software design description (SDD), the detailed design document traditionally required in defence, aerospace and other contract-driven projects. It borrowed the concepts of stakeholder, concern, viewpoint and view from IEEE 1471 (the predecessor of 42010) and lists design viewpoints such as context, composition, logical, dependency, information, interface, interaction, state dynamics, algorithm and resource. IEEE moved it to inactive-reserved status in 2020, but it is still cited in contracts and in teaching, and older programmes still deliver SDDs in its form. It sits closer to detailed design than to architecture.

Design documents and RFCs, used by many engineering organisations, are a different kind of template: a proposal for one change rather than a description of a whole system. They are covered in the next section but one, communicating architecture.

Conformance with ISO/IEC/IEEE 42010

ISO/IEC/IEEE 42010:2022 sets requirements for architecture descriptions and for architecture description frameworks (ADFs): established conventions, such as arc42 or the Views and Beyond approach, for producing descriptions in a given community. It does not prescribe a template, a notation or a process. A description conforms when it contains the information the standard requires, whatever template organises it.

In broad terms that means identifying the system described and its environment, identifying the stakeholders and their concerns, stating which viewpoints are used and which concerns each frames, providing views that follow those viewpoints, recording correspondences (how elements in different views relate) and recording the rationale for key decisions. arc42 does not claim conformance out of the box, and plain arc42 descriptions often lack an explicit link from each concern to the view that addresses it. The gaps are small and easy to close, as the table shows. Most teams do not need formal conformance; those in regulated industries or bound by contract sometimes do, and it is reassuring that a lightweight template can meet the standard with a few additions.

Making an arc42 description conform to 42010

42010 asks for	Where arc42 has it	What to add
Stakeholders and their concerns	Section 1.3 stakeholder table; quality goals in 1.2 and 10	List concerns explicitly per stakeholder, not just expectations.
Viewpoints, each framing named concerns	Implicit in sections 3, 5, 6 and 7	A short table naming each viewpoint, the concerns it frames and its notation (for example C4 container diagrams).
Views that follow the viewpoints	Sections 3, 5, 6 and 7	Nothing, if each view states which viewpoint it follows.
Correspondences between views	Partly in section 7 (what runs where)	Mapping tables, for example building block to deployment node, building block to owning team.
Rationale for key decisions	Sections 4 and 9 (ADRs)	Link each decision to the concerns it addresses.

Check your understanding

Which arc42 section usually becomes the largest, and how do you stop it growing out of control?

Section 5, the building block view. Keep level 1 to one diagram that fits on a screen and refine to levels 2 and 3 only for complex or risky building blocks.

Where in arc42 do quality goals appear, and how do sections 1 and 10 differ?

Section 1 lists the top three to five quality goals in priority order for orientation; section 10 refines them, and any further qualities, into a quality tree and concrete testable scenarios.

Your team already keeps ADRs in the repository. What should arc42 section 9 contain?

A link to the decision log, perhaps with a short list of the decisions every newcomer must read, rather than a copy of the records.

Does using arc42 make an architecture description conform to ISO/IEC/IEEE 42010?

Not automatically. Conformance depends on content: stakeholders, concerns, viewpoints, views, correspondences and rationale must be explicit, which usually needs a few small additions to arc42.

Next · 4.7Diagrams as codeWriting diagrams as text with PlantUML, Mermaid, Structurizr DSL and D2, drawing versus modelling tools, building documentation in the pipeline and the habits that keep it true.Continue →

← Decision records Chapter 4 overview

Sources and further reading

Have a question about this section? ArchitectBot, the course’s AI study assistant, answers from the course first.

Ask: “We have a 60-page architecture document nobody reads. How would I restructure it into a light arc42 description, and what could I safely delete?”