Brief introduction to arc42

Brief Introduction to arc42

arc42 ¹ is a template for architecture communication and documentation.
It is a proven, practical and highly pragmatic approach and takes the pain out of documentation.

arc42 provides everything you ever need to communicate and document your software architecture.
It's tool and technology agnostic, therefore can you use arc42 for arbitrary systems.
arc42 is open source and completely free to use.

This article provides a quick overview of arc42 and its parts.
For more information, please consult the (rather extensive) documentation [docsˆ] available on their documentation website (which, since V8/January 2022, contains several practical examples).

arc42 answers the following two questions in a pragmatic way and can be tailored to your specific needs:

• What should you document/communicate about your architecture?
• How should you document/communicate?

If you work under time or resource constraints, you will most likely skip certain parts of arc42. Our upcoming post on "lean documentation" will give guidance for such cases.

Before we dive in...

• Everything is optional - there is no need to fill in every section of the template. Treat arc42 documentation like the compartments of a cabinet, similar to the image below: The cabinet has a value, even if certain compartments remain empty.

(image by Jan Kolar from Unsplash)

• The order of these compartements is optimized for reading and understandability. You create your content in any order you like or your project requires. For example, in many development projects, the context (section 3) is defined and created first, followed by the top quality requirements (section 1.2).

• arc42 is completely tool-agnostic. You might create and maintain arc42 in your toolchain of choice: A wiki, a collection of Office documents, plain Markdown or Asciidoc, one of the commercial UML tools or even LaTeX. Whatever your tool of choice is, arc42 has you covered.

The structure of arc42

arc42 proposes a dozen sections (aka compartments) for your documentation.
These are organized top-down to improve understandability.

1. Introduction and goals

Short description of the requirements and driving forces of your system:

• Describe what the system delivers for its users in one or two sentences.
• Describe the two or three major use cases or features of the system.

• You should provide an extract or abstract of requirements.
  Restrict yourself to the top three (max five) quality requirements for the architecture, which have highest priority for the major stakeholders.

• Include a table of important stakeholders with their expectation regarding architecture or documentation.

2. Constraints

Anything that constrains teams in design and implementation decisions or decision about related processes. Constraints can sometimes go beyond individual systems and might valid for whole organizations and companies (e.g. company-wide technology choices or government regulations).
Time and money are common constraints in many organizations.

3. Context and scope

The context delimits your system from its (external) communication partners (neighboring systems and users).
It specifies or documents the external interfaces.
You should always document the context from a business or domain perspective.
If infrastructure or specific hardware plays an important role, you might also show a technical perspective.

4. Solution strategy

Summary of the fundamental decisions and solution strategies that shape the architecture. Can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions.

5. Building block view

Usually, boxes and arrows, showing the high-level code structure of the system. To phrase it a little more formal: The building block view explains the static structure of the system and contains, abstractions of source-code. It refines the context view, where the complete system is depicted as blackbox.

• Level 1 contains the major subsystems, components or parts of the system. In some cases, this coarse overview provides enough structural overview.
• Level 2 refines one or more elements from level 1: Create a separate whitebox (plus explanations) for every level-1 building block you like to explain in detail.

You can drill down to an arbitrary level of detail, but keep in mind the following:

Recommendation
Try to stick to level-1, as it often gives enough guidance and understanding for most stakeholders.

6. Runtime view

The runtime view explains the behaviour or processing of one or several building blocks.
It serves as companion to the static building block view from section 5 above.
The runtime view might explain important use cases or features, interactions at critical external interfaces, error and exception behaviour.

Recommendation
Use runtime scenarios primarily during development to validate or design building block structures. They help to identify missing or unnecessary dependencies. Keep only a small number of scenarios in your documentation

7. Deployment view

Software needs hardware to execute on, that's where the deployment view comes into play:
It shows the technical infrastructure with environments, computers, processors, networks and network-topologies.
In addition, it maps the software building blocks to those infrastructure elements.

8. Cross-cutting concepts

(aka cross-cutting concerns)

Overall, principal regulations and solution approaches relevant in multiple parts (→ cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architecture patterns and -styles, rules for using specific technology and implementation rules.

!

9. Architecture decisions

Keep a collection of architecturally significant decisions that are important, expensive, critical, large scale or risky including rationales, that are not recorded elsewhere.

Please use your judgement to decide whether an architectural decision should be documented here or whether you better document it locally (e.g. within the building block view or any cross-cutting concept).
You may have already captured the most important decisions of your architecture in the solution strategy.

Recommendation:
Use Architecture Decision Records to capture decisions in a simple, structured yet pragmatic way.

10. Quality requirements

Quality requirements, often described as scenarios.
You may use a quality tree to provide a high-level overview.
The most important quality goals should have been already described in section 1.2. (quality).

Let's look at some examples:

11. Risks and technical debt

Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about.

In case somebody reviewed or audited your system, their findings might be included here.

12. Glossary

Important domain and technical terms that stakeholders use when discussing the system.
Please include only specific terms - and avoid explaining REST, HTTPS or other words that have common explanations.

In addition, the glossary can serve as the translation reference if you work in a multi-language (international) environment.

Like what you saw?

Give it a try! Document a few of your architecture decisions, sketch your scope and context and explain a few key technical concepts - and you have your first version of your architecture documentation.

Download the template in a format you like. Unpack and start documenting. In case you have questions or want to see examples, consult the extensive documentation site ².

In case you want to know more, we have you covered:

• I wrote about the principles of technical documentation. That deep-dive article explains the fundamental requirements your technical documentation needs to fulfill - and many proven approaches how to achieve these.
• Another article on lean documentation is in the making, please stay tuned. Until then, watch the video "Sparsame Dokumentation" (oops, sorry, it's in German)

Comments or questions?

Leave a comment right below - or open an issue on the arc42 site. Otherwise, thanx for reading this article.

---

1. https://arc42.org. The template has been created by Dr. Peter Hruschka and Dr. Gernot Starke. They published the first version in 2005, after having used predecessor versions for many years in different large and medium-sized projects. ↩

2. https://docs.arc42.org. The extensive documentation website, containing more than 140 tips and 30 examples on how to use arc42. ↩