Search tools, AI agents, MCP servers
Submit a tool

Search iThub

Search tools, categories and collections. Type at least two characters.

Explore all tools
↑ ↓ to explore resultsEnter to open · Esc to close

Development & DevOps

How to make software architecture decisions: a practical guide

A practical guide to architecture decision making: spot the decisions that matter, weigh trade-offs, write an ADR, pick a process and know when to revisit.

iThub Insights cover: Guide, How to Make Architecture Decisions, with the iThub logo tile
On this page
  1. What counts as an architecture decision?
  2. Which quality attributes should drive the decision?
  3. Is it a one-way door or a two-way door?
  4. How much process does each type of decision need?
  5. How do you compare options fairly?
  6. What goes in an architecture decision record?
  7. What does a good ADR look like?
  8. Who makes the decision, and how do you get input?
  9. When is a formal architecture evaluation worth it?
  10. When should you decide, and when should you wait?
  11. How do you keep a decision true after it ships?
  12. How do you share decisions so people read them?
  13. When should you revisit or supersede a decision?
  14. Which anti-patterns derail architecture decisions?
  15. What should you check before accepting a decision?
  16. Sources

Architecture decision making is the practice of choosing, recording and revisiting the few technical choices that are expensive to change later, such as the primary data store or how services talk to each other. A workable process has six steps: confirm that the decision is architectural, write the quality attributes it must meet as measurable scenarios, judge how reversible it is, compare two to four options against weighted criteria, record the outcome in an architecture decision record (ADR), and state when you will revisit it. The effort each step gets should depend on the cost of being wrong.

This guide shows how to make architecture decisions in product teams where engineers and tech leads make these calls themselves. It includes an example ADR, a table of decision types and a checklist.

What counts as an architecture decision?

Michael Nygard, whose 2011 post made ADRs popular, described architecturally significant decisions as those that affect a system's structure, non-functional characteristics, dependencies, interfaces or construction techniques (Nygard). Three tests catch most of them:

  • Hard to reverse. Undoing it means migrating data, rewriting callers or renegotiating a contract. Swapping a logging library is cheap; moving two terabytes of orders is not.
  • Cross-cutting. It constrains more than one component or team. An event format that twenty consumers parse is architectural even when the code behind it is small.
  • Driven by quality attributes. The options differ mainly in performance, availability, security, cost or ease of change, not in features.

A choice that passes none of the tests belongs in code review. Typical architectural ones are the primary data store, synchronous calls versus events, splitting a monolith, service-to-service authentication, a public API's versioning policy, and building versus buying a core capability.

Which quality attributes should drive the decision?

Most architecture arguments are about which quality matters more. ISO/IEC 25010:2023, the current international product quality model, names nine characteristics: functional suitability, performance efficiency, compatibility, interaction capability, reliability, security, maintainability, flexibility and safety (ISO). Compared with the 2011 edition, usability became interaction capability, portability became flexibility, and safety is new.

Use the list as a prompt, not a scorecard. Three to five characteristics matter for any one decision, and they pull against each other: replicas raise availability and bring consistency problems, encryption costs latency, a flexible schema speeds up the first months and slows down reporting later.

"Fast" or "scalable" cannot settle a disagreement, so write each important attribute as a scenario that can pass or fail. Software Architecture in Practice by Len Bass, Paul Clements and Rick Kazman uses six parts: source, stimulus, environment, artifact, response and response measure. For example:

Under peak load (environment), a customer (source) submits an order (stimulus) to the order service (artifact). The order is stored and confirmed (response) within 300 ms at the 95th percentile (response measure).

Is it a one-way door or a two-way door?

Jeff Bezos split decisions into two types in Amazon's 2015 letter to shareholders, published in April 2016 (Amazon, 2015 letter). Type 1 decisions are consequential and close to irreversible: one-way doors that deserve slow, careful deliberation. Type 2 decisions are two-way doors that one person or a small group should make quickly, because a bad result means walking back through. He warns that growing organizations apply the heavy Type 1 process to Type 2 decisions too, and get slowness, risk aversion and too little experimentation. The 2016 letter added that most decisions should be made with about 70% of the information you wish you had (Amazon, 2016 letter).

Two cautions apply in software. Reversibility decays: a message format is easy to change while one consumer reads it and expensive once thirty do. And reversibility can be bought: an interface in front of a vendor SDK, a feature flag, dual writes during a migration or a tested data export each turn a one-way door into a two-way one, at the price of extra code. Pay it when the decision is uncertain and being wrong is expensive.

How much process does each type of decision need?

Match the weight of the process to the reversibility and reach of the decision:

Decision type Examples Reversibility Who decides Recommended process Record
Local design choice Module structure, a library inside one service Easy Developer or pair Code review Pull request description
Team technology choice Test framework, ORM, queue client Moderate Tech lead, with the team Short discussion, spike if unsure Short ADR
Cross-team contract API style, event schema rules, service auth Hard Named owner after the advice process RFC with a comment deadline ADR linked to the RFC
Platform or data store Primary database, message broker, cloud provider Very hard Owner, advisory forum, budget holder RFC, prototype, weighted matrix, scenario review Full ADR with options and evidence
Organization-wide standard Supported languages, deployment platform Very hard Architecture group or CTO, after open advice RFC, pilot team, migration plan ADR plus a published principle
Incident decision Regional failover, disabling a feature Varies Incident commander Decide now, review afterwards ADR within a week if it stays

How do you compare options fairly?

  1. Write the problem before the options. Agree on context, constraints and quality scenarios first, or the options will be one favorite and some straw men.
  2. Keep two to four real options, including the current solution when one exists. It is the baseline every change has to beat.
  3. Agree on weighted criteria before anyone scores. Weights add up to 100, and deal breakers are must-haves that act as gates rather than points.
  4. Score with evidence: a runbook, a load test result, the team's incident history with the technology.
  5. Check sensitivity. Shift the two largest weights by ten points. If the winner changes, you need better evidence on the criteria that swing it.
  6. Spike the riskiest assumption. A two-day prototype that measures the scenario nobody is sure about beats another page of comparison.

Treat a gap of a few percentage points as a tie; the weights are judgment calls.

When the options are products, iThub's software comparison matrix does the arithmetic: pick two to four tools from the directory, weight up to 20 criteria to 100%, mark must-haves (a tool scoring below 3 out of 5 on one is not ranked) and export CSV or PDF for whoever signs off. For the example below, the MongoDB vs PostgreSQL comparison and the PostgreSQL and MongoDB profiles are a starting point for evidence.

What goes in an architecture decision record?

An architecture decision record captures one decision with its context and consequences in a short text file; together, the records form the project's decision log (adr.github.io). Nygard's 2011 format has five parts: a numbered title, the context (the forces at play, described neutrally), the decision in active sentences ("We will..."), a status (proposed, accepted, deprecated or superseded) and the consequences, including the negative ones. He suggested one or two pages, sequential numbers that are never reused, and Markdown files in the repository.

Which ADR template should you start with?

MADR (Markdown Architectural Decision Records) adds decision drivers, the options considered with pros and cons, and a Confirmation section saying how compliance will be checked. Optional front matter records status, date, decision makers and who was consulted or informed, and files go in docs/decisions as nnnn-title.md. The adr.github.io templates page also lists one-sentence Y-statements. A reasonable default is Nygard's format for most decisions and MADR when three or more options are on the table, consistently within a repository.

Where should ADRs live, and do you need tooling?

Keep records next to the code, so they are reviewed in the same pull request as the change. Decisions spanning many repositories can live in a shared decisions repository. A wiki suits discussion but drifts from the code. To make records findable, the adr.github.io tooling page lists an ADR plugin for Backstage, and iThub's documentation tools can publish the log.

A template file is enough to start. adr-tools, Nat Pryce's shell scripts, creates numbered records with adr new, and adr new -s supersedes an old record and updates its status. Log4brains uses MADR by default and publishes the log as a static site.

What does a good ADR look like?

This record is hypothetical: the company, numbers and outcome are invented to show a useful level of detail, not to recommend a database for every order system.

# ADR 0012: Orders in PostgreSQL, merchant attributes
# in JSONB

Status: Accepted, 2026-11-10
Decision owner: Lead engineer, order platform
Consulted: Payments, data team, SRE

## Context

The order service is leaving the monolith. It stores
orders, line items, payments and refunds. Merchants add
their own attributes to line items.

Quality scenarios:
- An order is marked paid exactly once, even during a
  database failover.
- At 2x today's peak (about 600 writes per second), p95
  order submission stays under 300 ms.
- Finance joins orders, refunds and customers in daily
  reports without exporting data.

The team runs PostgreSQL in production with tested backups
and runbooks. Nobody has run MongoDB in production.

## Options considered

1. PostgreSQL: relational tables, JSONB for attributes.
2. MongoDB: one document per order, multi-document
   transactions for payments.
3. PostgreSQL for orders, MongoDB for attributes.

## Decision

We will use option 1, with foreign keys and check
constraints on payments and a GIN index on attributes.
Options 1 and 2 both met the latency scenario in a load
test. Option 1 scored higher on reporting and operability.
Option 3 adds a second store to keep consistent.

## Consequences

- Good: one database to back up, monitor and secure.
- Good: constraints enforce payment rules.
- Bad: attributes are validated in code, against a
  per-merchant JSON Schema.
- Bad: write capacity scales vertically.

## Confirmation

- CI fails if another service holds orders DB credentials.
- A weekly load test alerts if p95 exceeds 300 ms at 2x.

## Revisit when

- Sustained writes pass 1,500 per second.

It stays useful because the scenarios are measurable, the losing options say why they lost, and a trigger for reconsidering is stated. "We chose PostgreSQL because it is reliable" would not stop the same debate from starting again.

Who makes the decision, and how do you get input?

Every architecture decision needs one named decision owner who makes the call by a stated date and answers for it later. Shared ownership means a deadline or an outage decides instead.

RFCs and design docs. The proposer writes up the problem, options and a recommendation, sets a comment deadline, and turns the outcome into an ADR that links back. InnerSource programs use the same practice for decisions that cross team lines.

The advice process. In Andrew Harmel-Law's version for software architecture, anyone can make an architectural decision after seeking advice from everyone meaningfully affected and from people with relevant expertise (Harmel-Law). The decider need not follow the advice but must record it. He pairs it with ADRs, an architecture advisory forum, team-sourced principles and your own technology radar.

Disagree and commit. In the 2016 letter, Bezos describes people stating their disagreement and then fully backing a decision, so work keeps moving without consensus, and he applies it to himself. It works when the dissent is heard and written into the ADR's consequences, and fails when it is used to cut discussion short.

When is a formal architecture evaluation worth it?

The SEI's Architecture Tradeoff Analysis Method (ATAM) evaluates an architecture against its quality goals (SEI). A trained evaluation team works with architects and stakeholders, typically for three to four days, through nine steps that include building a quality attribute utility tree refined into prioritized scenarios and analyzing how the design handles the top ones. Outputs include risks, non-risks, sensitivity and tradeoff points, and risk themes.

A full ATAM suits systems where failure is very expensive. Most teams can borrow two pieces: a small utility tree from the quality scenarios, and a walk-through of the top scenarios that writes down every risk found.

When should you decide, and when should you wait?

Mary and Tom Poppendieck's Lean Software Development (2003) popularized the "last responsible moment": delay a commitment until not deciding would eliminate an important alternative. Apply it with care. Rebecca Wirfs-Brock noted in 2011 that the moment is hard to recognize, that decisions spread into other work, and that waiting can leave colleagues stuck (Wirfs-Brock). She preferred the "most responsible moment": decide early when others depend on the answer.

Waiting has a price. Don Reinertsen's The Principles of Product Development Flow (2009) argues that if you quantify only one thing, it should be the cost of delay. In architecture it shows up as blocked teams, workarounds that become permanent, and prototypes that reach production. An open decision holding up several teams may be the constraint in your delivery system, which is where the theory of constraints says attention pays off.

A practical rule: decide two-way doors now. For one-way doors, write down what you still need to know, how you will find out and by when, then decide on that date.

How do you keep a decision true after it ships?

An ADR records intent; fitness functions check that the system still matches it. Building Evolutionary Architectures by Neal Ford, Rebecca Parsons and Patrick Kua (2017; the second edition adds Pramod Sadalage) borrowed the term from evolutionary computing for any mechanism that objectively assesses an architectural characteristic, and the second edition presents fitness functions as automated governance (Thoughtworks). Examples:

  • A dependency test, with ArchUnit on the JVM or a short script elsewhere, that fails the build on a forbidden import.
  • A scheduled load test for a latency scenario.
  • A check that no service can reach another service's database.
  • Alerts on the service level objectives behind an availability scenario.

Name them in MADR's Confirmation section. A fitness function that keeps failing means the system has drifted or the decision no longer fits: reopen the ADR.

How do you share decisions so people read them?

Simon Brown's C4 model draws software at four zoom levels: system context, containers (applications and data stores), components and code, plus supporting diagrams for runtime behavior and deployment. It does not prescribe a notation or a tool.

Link each ADR to the diagram it changes and update both in the same pull request. Context and container diagrams cover most decisions; component diagrams go stale unless generated. Diagrams as code with Structurizr or Mermaid can be reviewed next to the records, and draw.io works when a hand-drawn view is clearer.

When should you revisit or supersede a decision?

Revisit a decision when its context changes: load or team size passes a threshold written in the ADR, a vendor changes pricing or licensing, a dependency nears end of life, a fitness function keeps failing, or an incident is traced back to the decision.

Do not rewrite an accepted ADR. Write a new record explaining what changed, mark the old one as superseded, and link both ways, as Nygard suggested; fixing a typo is fine. A quarterly look at records with a "revisit when" condition keeps the log honest.

Which anti-patterns derail architecture decisions?

  • Resume-driven development. A technology is picked because it looks good on a CV, then justified. Writing drivers and weights before naming options exposes it.
  • Analysis paralysis. There is always one more benchmark. Classify the door, time-box the work, set a date.
  • Decision by committee. Everyone must agree, so nobody owns the compromise. Name an owner and collect advice, not votes.
  • Undocumented decisions. The reasoning lives in one head or an old chat thread, so newcomers argue it again or fear touching it. Write the ADR, even late.
  • Decision by default. Nobody decided; the prototype shipped. Record "we keep what the spike used" as a decision.
  • Borrowed architecture. A design built for thousands of engineers brings its costs to a team of eight. Start from your own scenarios.

What should you check before accepting a decision?

  • It is hard to reverse, cross-cutting or driven by quality attributes.
  • Two to five quality scenarios have a measurable response.
  • It is classified as a one-way or two-way door, and the process matches.
  • One decision owner and a decision date are named.
  • Affected people and experts were asked, and their advice is recorded.
  • Two to four options were compared, including the current solution.
  • Weights were agreed before scoring and survive a sensitivity check.
  • The riskiest assumption was tested.
  • The ADR lists negative consequences.
  • A fitness function or check confirms the decision.
  • The ADR says when to revisit and links to the diagram it changes.

Sources

Frequently asked questions

What is the difference between an ADR and an RFC or design doc?

An RFC or design doc is the proposal: it explores the problem and options and collects comments before anyone decides, and it can run to many pages. The ADR is the short record of what was decided and why, kept with the code. Many teams link the RFC from the ADR so the full discussion stays one click away.

How long should an architecture decision record be?

Aim for something a new team member can read in five minutes, roughly one or two pages. If a record grows much longer, the extra material is usually analysis, which reads better as a separate design doc linked from the record.

Should we write ADRs for decisions made years ago?

Only for old decisions that still shape the system and keep coming up in discussions. Write down what you know, give the record today's date, and say plainly that the original reasoning was reconstructed. Backfilling every historical choice costs more than it returns.

Who writes the ADR and who approves it?

Usually the person who proposed the change or owns the decision drafts it. For team-level choices, merging the pull request that adds the record is the approval. Cross-team decisions need review from the affected teams before the status changes from proposed to accepted.

Are architecture decisions different from design decisions?

The line is blurry and depends on scope and cost of change. A choice confined to one module that a developer could undo in an afternoon is design. A choice other teams build on, or one that would take a migration to undo, is architecture. When in doubt, a short ADR costs little.

Do ADRs fit agile teams?

Yes. A record is written at the moment a decision is made, takes minutes rather than days, and is reviewed in the same pull request as the code. That fits iterative delivery better than an upfront architecture document that nobody updates.

Can a decision be reversed after the ADR is accepted?

Yes, and that is normal. The accepted record stays as history, and a new record explains the new choice and why the situation changed. Reversals documented this way show a team learning, not a team failing.

Tools in this article

  1. PostgreSQLOpen source object-relational database with extensionsDatabases10 views
  2. MongoDBDocument database with transactions, sharding and AtlasDatabases8 views
  3. BackstageOpen source framework for building developer portals around a software catalog, templates and TechDocsPaaS & App Deployment7 views
  4. MermaidJavaScript library that renders flowcharts, sequence diagrams and 30+ other diagram types from textDiagramming & Whiteboards0 views
  5. Ddraw.ioDiagramming and whiteboarding app with Apache 2.0 source codeDiagramming & Whiteboards1 views
Share this article

Facts link to their official sources. Product details can change after publication: report an error or read the editorial methodology.

Emanuel DE ALMEIDA

Written by

Emanuel DE ALMEIDA

Entrepreneur · IT consultant · Software creator

Geneva-based entrepreneur, IT consultant and creator of SuniPDF and SuniCapture. Emanuel shares practical IT, cybersecurity and software insights on iThub.

Keep reading

More guides and analysis from the iThub editors.

All insights
What is Boolean logic? Operators, truth tables and how IT teams use itWhat is Boolean logic? AND, OR, NOT, truth tables, De Morgan's laws, short-circuiting, SQL NULL and bitmasks, with tested examples for developers and IT.What is InnerSource? Principles, roles, patterns and how to startInnerSource applies open source practices inside a company. Its principles, roles, InnerSource patterns, how it differs from open source and how to start.12 open source projects for developers to know in 202612 open source projects for developers in late 2026, from Ghostty and Tauri to Langfuse and Zerobyte, with licenses and latest releases checked.