arc42 Software Architecture Template


  1. What is software architecture?

  2. What is arc42?

  3. Sections in arc42

What is Software Architecture?

All architectures are design, but not all designs are architecture.

Architecture represents the set of significant design decisions that shape the form and the function of a system, where significant is measured by the cost of change.

— Grady Booch


What should we document and communicate about our architecture?

How should we document and communicate it in an agile environment?

How can we minimize the effort for the software architecture documentation?

How can stakeholders access the versioned documentation?

Known Problems

  • Not existing or outdated documents

  • Confusing and without a clear structure

  • Process-oriented instead of result-oriented
    How instead of Why

  • Painful to maintain


  • Documentation as code under version management

  • Optimized for understandability and adequacy

  • Developers are interested to create and maintain the documents with manageable effort

  • Follow standard to reduce training and internal resistance

arc42 Sections

00 arc42 overview

1 - Introduction and Goals

01 intro and goals
  • Business goals and essential features

  • A short description of the requirements

  • A few quality goals for the architecture

  • List of important stakeholders and expectations

1: Tips


Provide context

Do not skip this

Cover the important bits

Avoid going into details

Use diagrams C4, UML

Do not make this too long

Use concrete examples specification by example

Avoid verbosity

2 - Constraints

02 constraints overview

Anything that constrains teams in design and implementation decisions.

  • Environmental and legal aspects

  • Company-wide or organizational constraints

  • Technical limitations

3 - Context and Scope

03 context overview
  • Separate your system from its external systems and users.

  • Specify the external interfaces shown either in a business and technical perspectives.

  • List of communication interfaces

3: Tips

  • Select tools which can be integrated into our continuous delivery pipeline

  • Prefer artifacts you can store in Git

  • Follow standards

4 - Solution Strategy

04 solution strategy overview

Fundamental decisions and solution strategies

  • Technology decisions

  • Top-level decomposition

  • Approaches to achieve top quality goals

  • Relevant organizational decisions such as the development process

5: Building Block View

05 building block overview

A static decomposition of the system, shown as hierarchy of white boxes up to the right level of abstraction. Elements are modules, components, subsystems, classes, interfaces, libraries, frameworks, or partitions.

Historical Background

UML and 4+1 Architectural View heavily influence the arc42 approach.

05 4 1 view of sw architecture


C4 Model is a model is a set of hierarchical abstractions

System Context Diagrams

C4 Context

Container Diagrams

C4 Container

Component Diagrams

C4 Component

Code Diagrams

C4 Code

6 - Runtime View

06 runtime overview

Behavior of building blocks as scenarios, covering use cases, operation, administration, error handeling and features.

Examples for this might be UML sequence, activity or state machine diagrams.

6 - Tips

  • Runtime scenarios explain important application behavior

  • Maintaining runtime scenarios is expensive

  • You often can explain behavior with unit tests to document how the system behaves

7 - Deployment View

07 deployment overview

The technical infrastructure with environments, servers and topologies.

Mapping of building blocks to the right infrastructure.

UML offers deployment diagrams to express that view

7 - Tips

  • You can often describe your system topology with a Docker compose file.

  • API are described with {ref-openapi}.

8 - Crosscutting Concepts

08 concepts overview

Principal regulations and solution approach relevant in multiple parts of the system.

  • domain models, architecture patterns and design patterns

  • rules for using specific technology, technical consequences of overall decisions

  • implementation rules

8 - Tips

08 crosscutting concepts

9 - Architecture Decisions

09 decision overview

Important, expensive, critical, large scale or risky architecture decisions including rationales.

Use the Architecture Decision Record ADR approach to document such decisions.

9 - Architecture Decision Record

09 adr details

Smaller pieces of documentation are easier to read, create and maintain. When it comes to architecture decisions, development teams often will:

  • Know about the decision, as it is visible in the source code

  • Miss the motivations behind that historical decision

10 - Quality

10 q scenario overview

Quality requirements as scenarios. The quality goals can be taken from section 1 Introduction and goals.

10 - Tips

  • Explore fitness functions

  • Use static code analysis

  • Write automated unit and acceptance tests

  • Install monitoring

  • Promote defect-driven development

11 - Risks and technical Debt

11 risk overview

The known technical risks or already present technical debt.

What potential problems exist in the application itself or its surroundings?

What does the development team fear for the future?

11 - Tips

Risk management is project management for grown-ups.

— Tim Lister

Each risk has a description, an associated cost, a probability, and a set of mitigation measures.

12 - Glossary

12 glossary overview

Important domain and technical terms that stakeholders use when discussing the system.

Translate in other languages if there are multiple languages spoken in your company.

Lessons Learnt


I generate most of the content into the following sections:

  • 5 - Building Block View

  • 8 - Crosscutting Concepts

  • 9 - Design Decisions ADR

  • 13 - User Interface

Used Techniques

used techniques


00 arc42 logo