Architecture Planning tool

arc42

Structures architecture knowledge across goals, context, runtime, deployment, decisions and risks.

Core question

What system context, constraints, and decisions must the architecture communicate?

Plan arc42 Method guide

Start comparison

Give feedbackIs this method useful to you?

Participants: 1-4
Time: 1-2 Tage

The steps are a practical sequence; adapt them to the method’s purpose and available evidence.

A paper-based illustration representing arc42 with its core stages and visible working result.

Scope
Set system and documentation need
Name the system, stakeholders, key quality goals and documentation purpose; select relevant arc42 sections.
Goals
Document goals, constraints and context
Write prioritized quality scenarios, sourced constraints, system context and interfaces.
Views
Develop strategy and views
Describe key decisions and only the building-block, runtime and deployment views needed to explain them. Link diagrams to text.
Upkeep
Maintain quality, decisions and risks
Record important decisions with status, risks and assumptions; link scenarios and assign update triggers.

Revisit the model when evidence, context or outcomes change. Record what changed and why.

A good fit when

Use it when: Living Architecture Docs, Team Handover. The group can provide the evidence and authority the method requires.

Ideal for

Living architecture docs
Team handover
Complex systems

Not good for

Throwaway projects
Teams without documentation needs

Outputs

arc42 architecture documentation
Selected architecture sections with quality scenarios, context, decisions and maintenance triggers.
Living arc42 documentation
The artifact records scope, date, participants, source version, and owner, including changed assumptions and the reason for each revision.

arc42 architecture documentation

Fictional worked example

Fictional, “Practice Portal” system: top quality goal is availability during practice hours. Context: patients and practice administration; no direct payment processing. Strategy: initially use a synchronized availability copy. Runtime: reserve a slot, await confirmation, show alternatives on conflict. Risk: delayed synchronization. Maintain sections 1, 3, 4, 6 and 10 first; mark other sections as deliberate gaps.

Introduction and Goals

Record stakeholders, requirements and top quality goals.

Fictional: availability during practice hours is a priority.

Constraints

Name technical, organizational and regulatory constraints.

Privacy requirements and existing practice system.

Context and Scope

Explain boundary, external partners and interfaces.

Patients and practice management; no payment processing.

Solution Strategy

Explain guiding approaches and key architecture decisions.

Availability copy with conflict check.

Building Block View

Show relevant building blocks and responsibilities.

Booking API, web app, appointment database.

Runtime View

Describe critical scenarios and interactions.

Reserve slot; await confirmation.

Deployment View

Map infrastructure and software components.

Hosting and practice integration remain open.

Crosscutting Concepts

Document recurring concepts and rules.

Authentication and audit logging.

Architecture Decisions

Link important decisions with status and rationale.

Synchronization approach under review.

Quality Requirements

State quality scenarios measurably.

Fictional scenario: With the calendar copy available, 95% of slot searches during practice hours return availability within 2 seconds.

Risks and Technical Debt

Record risks, impact and response.

Stale availability may cause double booking.

Glossary

Define domain terms consistently.

Slot means a released time period.

The example text is fictional; replace it with sourced project information.

arc42 at a glance

First step

Name the system, stakeholders, key quality goals and documentation purpose; select relevant arc42 sections.

Open the method guide

Good to do first

Architecture

Architecture Inception Canvas

Supplies the business case and early quality goals as the doc's starting point.

Where to go next?

Architecture

C4 Model

Fills the building-block-view chapter with the matching C4 diagrams.

Paper illustration of two considered options leading to a decision record with a marked status and visible consequences.

Architecture

Architecture Decision Record

Records each decision surfaced in arc42 as its own dedicated entry.

Deep dive

Purpose

arc42 structures architecture knowledge so teams can document system, decisions, and risks consistently. The template builds a living understanding of the architecture instead of scattered notes.

How it works

The team fills in the relevant chapters from context through building blocks to runtime, deployment, and risks. Content is kept concise, referenceable, and connectable so documentation and conversations share the same basis. The result is a coherent architecture profile that eases maintenance and handovers.

In detail

The arc42 structure organizes architecture knowledge into recognizable chapters and ties conversations, onboarding, and maintenance to the same documentation logic. Good use fills only the sections that provide real orientation for the specific system and links decisions instead of piling up text mass. The benefit grows when the documentation keeps growing alongside the system instead of being completed hastily right before a handover.

Facilitation

Anchor arc42 to existing architecture conversations, reviews, and change occasions so the format gets used day to day instead of just opened once. The turning point becomes visible when a chapter first speeds up a real decision or clarification. Close with a lean starting structure, clear maintenance ownership, and a few prioritized sections for the next iteration.

The method guide walks execution through 4 phases, timing, 4 pitfalls, and clear stop criteria.

Open method guide

Your perspective

Does this method help with your work?

Your feedback helps shape the next improvements to methodatlas.

Sources and topics

Topics

Architecture Documentation Communication

Sources

arc42 at a glancearc42.orgarc42.org by Peter Hruschka and Gernot Starke; describes the twelve sections of the arc42 architecture documentation template.

In playbooks

Build Architecture DocumentationMove from scattered architecture knowledge to views, decisions, and communicable documentation.

Artifact templates

arc42: WorksheetPrepare the decision, source evidence and next review.

markdown

arc42-working-template.md

Prepare the decision, source evidence and next review.

arc42: Worksheet

Question

To be confirmed

Desired outcome

To be confirmed

Scope

Run the method Time: See catalog planning range; no universal duration.

Complete this worksheet on paper or in your own document during the work.

Preparation for this scope

Method setup

Materials: Shared visual workspace, source evidence, and an agreed decision question.
Roles: Architect, developers, operations, domain stakeholders, decision owner.
Advance information: Collect existing data, examples, constraints and relevant stakeholder perspectives.
Overall time needed: Several focused sessions; size by system complexity and available evidence.
Setup: Choose system, audience, level of detail and living-document owner. Capture business goals, quality goals and binding technical/organizational constraints. Describe external actors/systems, scope and the few decisions shaping the solution. Document relevant building blocks, runtime scenarios and deployment view only as needed. Link quality scenarios, risks, decisions and glossary; assign update triggers.