Skip to content
Software Architecture Guide

Architecture Principle

Explanation

Section titled “Explanation”

An architecture principle is a guideline for a whole class of problems. It is cohesive, prescriptive and supports decisions. It does not name the solution. It limits the range of options, like a guardrail rather than a gate. That limit helps teams decide faster.

Principles and decisions. Principles record the priorities and beliefs that guide reasoning. Decisions are the actual unit of architectural work (see Architectural Decision). A principle justifies a decision. It also restricts how the architecture is designed, while the requirements are still met.

Reflect real values. A good principle shows what the organization values most when it must compromise. It therefore depends on the organization’s context. A generic statement that fits everyone says little.

How to write one. A useful formulation has five parts:

  • the statement itself;
  • the rationale, which should tie to stakeholders and their goals;
  • the consequences;
  • the exceptions, meaning situations where deviation is acceptable;
  • the relations to other principles.

The rationale should support discussion. See Architecture Principle Structure for details.

Exceptions and review. Sometimes a team sets a principle aside for good reasons. If that happens repeatedly, the principle may need a review. One source suggests three justified exceptions as a trigger.

In arc42. The solution strategy lists the key decisions that form the cornerstones of the architecture. It should keep them short, motivated and justified. Principles fit naturally there. See Solution Strategy.

Example

Section titled “Example”

A company states this principle: “Prefer packaged products over custom code.” The rationale says the business wants features quickly and has a small team. A consequence is that teams must justify any custom build. An exception covers a feature that gives the company a unique edge. When a team plans a new billing function, the principle removes “build from scratch” as the default option. The team then compares packaged products.

Trade-offs

Section titled “Trade-offs”

Principles involve trade-offs. For example, a principle that favors packaged solutions saves effort. But heavy customization of such packages raises maintenance costs. Teams need to balance the two. A principle that is too rigid can also block sensible choices. Listing exceptions, and reviewing a principle when exceptions pile up, keeps it useful.

Checks

Section titled “Checks”
  • Each principle has a statement, a rationale tied to stakeholder goals, consequences, exceptions and relations.
  • The principles reflect what the organization values when it must compromise, not generic statements.
  • Principles narrow the options instead of dictating a single answer.
  • Repeated justified exceptions to a principle trigger a review of it.
Section titled “Related”

Sources

Section titled “Sources”