Skip to content
Software Architecture Guide

Architectural Design Issue

Explanation

Section titled “Explanation”

A design issue is a concern that calls for a decision. You write it as a concise question. One example is “Which concept is used to decompose the system under construction into logical building blocks?” Keep to one concern per question.

A decision means selecting one alternative based on given criteria. So every issue needs two more things next to the question: the criteria, often called drivers, and the options. Criteria should come from real requirements and experience. These are the forces behind the decision. See the article Architectural Force for more.

How an issue is resolved

  1. State the question.
  2. Name the criteria. One example is the ability to exchange system parts without affecting others.
  3. List the options. The decomposition example lists three: Layers, Pipes-and-filters and Workflow.
  4. Choose one option. The others are rejected, or kept as fallbacks.

You should also evaluate the options you did not choose, not only the winner. Readers can then see why the alternatives lost.

Recording the issue

Stakeholders should be able to understand and retrace your decisions. Section 9 of arc42 recommends Architectural Decision Records (ADRs) for this. An ADR describes the situation, including technical, political, social and project aspects. See the articles Architectural Decision Record and arc42 Architecture Decisions.

Example

Section titled “Example”

A team building an online shop asks: “How do we split the system into building blocks?” The criterion is that the team wants to change checkout without touching the catalog. The options are layers, pipes-and-filters and a workflow-based design. The team weighs each option against the criterion and picks layers. It notes why the other two lost and keeps one as a fallback. The ADR holds the question, the criteria, the options and the choice.

Trade-offs

Section titled “Trade-offs”

Every selection brings benefits, but it also comes at a price. The rationale should say what you gain and what you give up. Arc42 asks you to list all consequences of a decision, not only the positive ones. Evaluating neglected options takes extra effort, but it makes the decision easier to retrace.

How a design issue is resolved

Diagram source 
flowchart LR
  Q[Issue as a question] --> C[Criteria / drivers]
  Q --> O[Options]
  C --> E[Evaluate all options]
  O --> E
  E --> D[Choose one]
  D --> R[Record rationale in ADR]

Checks

Section titled “Checks”
  • Each design issue is phrased as a concise question.
  • Each issue lists its criteria (drivers) and its options.
  • Rejected options are evaluated too, not only the chosen one.
  • The rationale names the price of the choice and lists negative consequences too.
  • The criteria are rooted in actual requirements and experience.
Section titled “Related”

Sources

Section titled “Sources”