Skip to content
Software Architecture Guide

Architecture as Set of Design Decisions

Explanation

Section titled “Explanation”

One way to see software architecture is as the set of important design decisions about a system. A design decision is a choice about how the system is built. Not every choice counts. Architecture covers the ones that are important, expensive, large-scale or risky.

What makes a decision important

  • It addresses a requirement with a measurable effect on the architecture and on the quality of the system. The ADR community calls this an architecturally significant requirement (see Architecturally Significant Requirement).
  • It is hard to change once made. Integration style is one example: switching from one style to another is costly.
  • It is large in scale or risky. What counts as important also depends on the scale you look at. A choice that matters to one team may be minor for a whole organization.

Architecture is more than a diagram

Architecture is not a fixed diagram. One view, cited by Fowler, is that architecture is the shared understanding expert developers have of the system design. That understanding includes why the system looks the way it does.

Why the cost of change matters

Fowler argues that internal quality, which good architecture provides, lowers the cost of future change. Decisions that are expensive to reverse deserve care up front.

Recording decisions

Teams can see a decision in the code. They often cannot see the motivation behind it. So arc42 section 9 asks you to record important, expensive, large-scale or risky decisions with their reasons. It advises documenting only a few important decisions, not all of them. Fowler describes an architecture decision record (see Architectural Decision Record) as a way to let people understand, long afterwards, why the system is built the way it is.

Example

Section titled “Example”

A team building an order system decides that all services will talk to each other through a message queue instead of direct calls. Switching later would mean rewriting every service, so this is a principal decision. The team records it with its reasons. Choosing the color of a button is also a design decision, but it is cheap to reverse and does not belong in the architecture record.

Trade-offs

Section titled “Trade-offs”

Treating every choice as architectural buries the important ones and creates documentation nobody reads. Treating too few as architectural leaves expensive choices unexamined. Because importance depends on scale, teams must agree on where the line sits for their context. Recording the reasons takes effort, but without it later teams see only the code and not the motivation.

Checks

Section titled “Checks”
  • The architecture documentation lists the important, expensive, large-scale or risky decisions together with their reasons.
  • Only a few important decisions are documented, each with its motivation, instead of every choice.
  • Each documented decision is tied to an architecturally significant requirement.
  • Decisions that are costly to reverse, such as the integration style, are explicitly identified.
Section titled “Related”

Sources

Section titled “Sources”