Skip to main content

What an Architecture Decision Is vs a Design Decision

What This Concept Is​

An architecture decision is a choice that shapes the structural or quality properties of a system, is expensive to reverse, and is visible across team or component boundaries. A design decision is a choice that lives inside one component, is cheap to change, and is invisible from outside.

The two categories blur at the edges on purpose. What matters is the test:

  • Blast radius. If the decision is wrong, how many teams, services, or release trains feel it?
  • Reversal cost. What is the cost and risk of backing out six months from now?
  • Externalized constraint. Does this choice impose something on other teams, whether they know it or not?

If any of those three answers is "many / high / yes," treat it as architectural.

Why It Matters Here​

You cannot write good ADRs if you cannot tell what a decision is. Teams waste effort two ways:

  • they ADR every design choice (variable names, formatting, internal package structure) and the record becomes noise
  • they ADR nothing, so the choices that lock the organization for years live only in a Slack thread

Separating architecture from design is also the entry point for the rest of the module: reversibility (Concept 3), ATAM (Concept 7), and fitness functions (Concept 13) only make sense once "architectural decision" has a working definition.

Concrete Example​

Two related decisions on the same PR:

  1. "We will use PostgreSQL as the primary relational store for the Orders service."

    • Blast radius: every downstream consumer that queries Orders; ops team owns backup and HA.
    • Reversal cost: high - data migration, client changes, ops retraining.
    • Externalized constraint: yes - other services must speak Postgres idioms (jsonb, LISTEN/NOTIFY) or not.
    • Architectural. Write an ADR.

  2. "Inside Orders, we will use the Repository pattern for data access."

    • Blast radius: Orders service code only.
    • Reversal cost: a week of internal refactoring; no external API change.
    • Externalized constraint: no.
    • Design. Code review is enough.

Same pull request, different categories.

Common Confusion / Misconception​

"If it's written in the system diagram, it's architecture." No. Diagrams include plenty of design detail. The test is effect, not medium.

"Only senior people make architecture decisions." False and dangerous. Anyone who chooses something with broad blast radius has just made an architectural decision; the role question is who reviews it, not who made it.

"ADR bureaucracy." Writing an ADR for every micro-decision is not rigor, it is avoidance. If the answer to "could one person change this in an afternoon with no coordination?" is yes, it is not architectural. The cost of a bad ADR is worse than no ADR, because future readers trust the record.

How To Use It​

Before capturing a decision, run the three-question filter:

  1. Blast radius - can I name at least two teams or services the wrong answer would hurt?
  2. Reversal cost - if I had to back this out in 12 months, would I need a migration plan?
  3. Externalized constraint - does this impose something on someone who is not in this PR?

Two "yes" answers: write an ADR. One "yes": probably a design note, possibly an ADR if consequences are non-obvious. Zero: design decision, handled in code review.

When in doubt, write a short draft ADR and let the reviewer classify it. The worst outcome is "this is just a design choice, let's drop this" - which still took 15 minutes.

Check Yourself​

  1. For each of these, classify as architecture or design and justify: (a) switching from REST to gRPC for inter-service calls; (b) renaming an internal helper function; (c) choosing React Query vs manual fetching inside one frontend; (d) adopting a shared logging library across all services.
  2. Name one decision you have seen that looked like design and turned out to be architecture. What made it escalate?
  3. Who should be able to veto an architecture decision at your organization? Who should not need to approve one?

Mini Drill or Application​

Take 5 recent decisions your team made (last 30 days). For each, answer:

  • blast radius (teams / services affected)
  • reversal cost (low / medium / high)
  • externalized constraint (yes / no)
  • classification (architecture / design / borderline)
  • if architecture and no ADR exists, draft a one-paragraph ADR stub

Expect 1-2 to be architectural even if none were treated that way at the time. That gap is the point of the drill.

Read This Only If Stuck​