arc42
arc42 is an outline for architectural descriptions. It combines requirements, solution strategy, building blocks, runtime, deployment, decisions and risks.
- ObjectivesQuality goal at the beginning.
- SiftingStructure and Runtime.
- ReferencesConnecting decisions and risks.
Context
Why this is important
Good singles charts help little if no one sees how goal, structure, flow, decision and risk are related. arc42 gives these things fixed places that point to each other. Individual views have their own building blocks.
This building block shows the structure and interconnections of an architectural description. C4 and sequence diagrams provide possible views; ADRs record individual decisions.
At a glance · arc42 as structure
Completed arc42-building blocks for the shop
The shop documentation links the destination for order confirmations with payment expiration, rollout, ADR to the module structure and an open restore risk.
This is how you read the picture
- Objectives Section “Context and objectives”: Order confirmations visible in the agreed time budget.
- Sifting Sections “Building block view” and “Term view”: order, payment and dispatch with the payment expiration.
- References Sections ‘Decisions’ (ADR)01) and “risks” (restore duration unmeasured.
- Context and objectives
- Order confirmations should be visible within the agreed time budget; the payment provider is outside the shop boundary.
- Solution strategy
- The shop remains a modular monolith. The payment module clarifies pending results via the payment identification code of the external provider.
- Building block view
- Order has order status and module contract; payment has authorization identifier and provider adapter; shipping processes confirmed orders.
- Maturity view
- Order passes the payment order to payment; payment calls the provider and returns the confirmed status.
- Decisions
- ADR-01 Choose the modular monolith with separate module responsibilities and an external payment connection.
- Risks
- The duration of a restore with payment reconciliation is unmeasured; the operating team conducts an isolated sample.
Benefits & limitations
Helps if:
- Development, business and operations teams benefit from a shared starting point for goals, structure and operational questions.
- Long-term handovers and changes need discoverable decisions and risks.
Boundaries
- Empty or unnecessary chapters do more harm than good; start with answers that support decisions and operations.
- Duplicate content drifts apart; link authoritative sources and name their maintenance owners.
- arc42 provides organisation; C4 and Sequence diagrams provide diagrams, and the ADR provides rationale.
In practice
- Identify readers and information needs. State who uses the description for which decisions. Prioritise questions about structure, runtime, quality and risk by actual need. This defines a tailored documentation scope.
- Link goals and evidence. Connect quality goals to strategy, views, decisions and suitable operational information. Link authoritative artefacts and make their relationships discoverable; changes remain traceable at the source.
- Identify gaps and maintenance ownership. Mark open assumptions, risks, owners and update triggers. Review the description when relevant changes occur. This keeps the information structure maintained and open issues visible.
Read the detailed explanation
arc42 structures architecture descriptions around topics such as goals, constraints, context, strategy, building blocks, runtime, deployment, concepts, decisions and risks. Section depth follows actual need; arc42 organises questions and answers them through suitable Architecture views and Architecture decisions.
Connections make the description useful: a quality goal justifies a strategy reflected in building blocks and workflows. Existing sources can be linked to avoid maintaining information twice. Ownership and update triggers keep content reliable. arc42 organises relevant answers into a coherent knowledge structure for its readers. The outline links authoritative sources and may span several maintained artefacts. Information continues to be maintained at its authoritative source.
Gernot Starke and Peter Hruschka developed arc42, which is freely available as a template.
Check your understanding
Test yourself in three stages
ReadingCheck in the picture
Which arc42 section calls the open restore risk?
View the solution with justification
The “Risks” section: The duration of a restore with payment reconciliation is unmeasured.
ApplyingTransferred to a new situation
The team introduces a payment timeout as a quality goal. Which sections do you edit?
View the solution with justification
Enter the goal under “Context and Objectives” and refer to it from “Solution Strategy” and “Term-Term Approach”. An operating indicator makes compliance observable.
EvaluateWeighing an alternative
Would a collection of loose diagrams instead of arc42 be sufficient? Weigh in.
View the solution with justification
Loose diagrams are created quickly. Without a fixed structure, however, goals, decisions and risks are missing, and it is unclear what belongs together; arc42 costs care for this.
Explore further
These building blocks continue the thoughts of this page.
References
- arc42 – Template Overview (opens in new tab)Shows the twelve sections and their tasks in an architectural documentation.
- arc42 – Building Block View (opens in new tab)Explains hierarchical decomposition and documentation of building blocks.
- arc42 – Runtime View (opens in new tab)Describes how important flows and interactions are documented.