arc42 Software Architecture Template

Marcel Baumann (tangly llc)

Agenda

What is software architecture?
What is arc42?
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

Ideas

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

Concepts

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

1 - Introduction 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

Prefer	Avoid
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

Prefer

Avoid

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

Anything that constrains teams in design and implementation decisions.

Environmental and legal aspects
Company-wide or organizational constraints
Technical limitations

3 - Context and Scope

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

Fundamental decisions and solution strategies

Technology decisions
Top-level decomposition
Approaches to achieve top quality goals
Relevant organizational decisions such as the development process

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.

C4

C4 Model is a model is a set of hierarchical abstractions

System Context View shows the system scope
Container View decomposes the applications and data stores
Component View decomposes containers into interrelated components
Code View provides details about the design and is based on UML

System Context Diagrams

Container Diagrams

Component Diagrams

Code Diagrams

6 - Runtime View

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

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

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

9 - Architecture Decisions

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

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

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

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.

Atlantics
— Tim Lister

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

12 - Glossary

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

Effort

I generate most of the content into the following sections:

5 - Building Block View
8 - Crosscutting Concepts
9 - Design Decisions ADR
13 - User Interface