Architecture

Architecture Decision Making

How experienced engineers turn a vague architectural problem into a documented, defensible decision — and how ADRs, criteria, reversibility, and revisit triggers keep that decision useful over time.

Mangesh MandlikLast updated: 2 November 2026

What Is Architecture Decision Making?

Architecture decision making is the discipline of turning implicit choices into explicit, documented, and reviewable decisions. A recurring, costly pattern is architectural choices made implicitly — without naming the requirements they had to satisfy, the alternatives that existed, or the conditions under which they should be revisited.

An Architecture Decision Record (ADR) captures the problem context, decision drivers, options considered, the decision, and the consequences that follow. Recording rejected alternatives is often especially valuable because it preserves why a plausible option was not chosen at that point in the system's evolution.

What a useful ADR should capture

→ Context and problem statement
→ Decision drivers: requirements, constraints, and assumptions
→ Options considered, including rejected alternatives and why they were rejected
→ The decision itself and its expected consequences
→ Revisit trigger: what would change the decision
→ Status or supersession note when a later ADR replaces it

More reversible

Limited adopters, low migration cost, and small blast radius. Decide faster, then validate with evidence.

Hardening factors

Data gravity, external contracts, many dependent consumers, and more teams depending on the choice make reversal slower and riskier.

Change Trigger

"Revisit this if..." prevents a once-reasonable decision from fossilising after requirements or adoption change.

Visual Story

Why synchronous coupling fails — and how a queue fixes it

Architecture Decision Making

Hidden Coupling

0 / 0

💥Up nextFailure Cascades

⤢ Expand for synchronized narration timeline

Watch how the system behaves under failure in each architecture. The queue absorbs inventory unavailability — but introduces eventual consistency as a consequence. That trade-off is what the ADR must record.

Problem It Solves

Why implicit decisions are dangerous

Without documented architectural reasoning, every new engineer re-evaluates every decision from scratch — often re-selecting options that were already rejected for reasons no longer visible. This wastes time, introduces inconsistency, and accumulates technical debt silently.

Good decision records also make later architecture reviews faster and more grounded: reviewers can challenge assumptions, revisit triggers, and evidence gaps instead of reconstructing history from memory.

The Decision-Making Process

Five steps from problem to documented decision

Frame the problem correctly — Define the problem at the requirement level, not the solution level. "We need Kafka" is a solution. "Order notifications must be at-least-once and not fail when inventory is down" is the problem.

Separate requirements from constraints — Requirements: what must happen. Quality attributes: latency, availability, durability. Constraints: hard limits — no Kafka experience, capped budget, data must stay in EU.

Treat reversibility as a spectrum — Ask what makes reversal hard: data gravity, external integrations, adoption, migration cost, blast radius, and the number of dependent teams. A decision that feels reversible on day 1 can harden over time.

Agree criteria before evaluating — Define evaluation criteria before exploring options. Criteria set afterwards unconsciously favour the preferred option.

Record decision + consequences + revisit trigger — Document the context, decision, consequences, assumptions, rejected alternatives, and the condition under which this decision should be revisited or superseded.

How Architects Think

What separates good architectural decisions

The sign of a mature architectural decision is not that the team found the "best" technology in the abstract. It is that they chose the right technology for these requirements, these constraints, and this stage of the system — and recorded enough reasoning that a future team can tell when the answer should change.

Reversibility is not binary. A queueing choice with one producer and one consumer may be easy to replace; the same choice becomes much harder once five teams consume the schema, dashboards depend on it, and a migration would require replaying months of data.

One of the most useful sentences in an ADR is the change trigger: "Revisit this decision if..." — it separates an architecture that evolves intentionally from one that is silently outgrown.

Illustrative Scenario

Decoupling order placement from inventory — worked end-to-end (illustrative scenario)

Context: a team is extracting an inventory service from a monolith. The order service needs to notify inventory when an order is placed. Currently this is a direct in-process call; the team must choose what replaces it.

Requirements: at-least-once delivery. Order placement must not fail when inventory is temporarily unavailable. Notification latency up to 5s.

Constraints: team of 4 with no Kafka experience. Infrastructure cost is capped. The notification schema is expected to be stable.

Criteria agreed before evaluation: availability decoupling, at-least-once delivery, retention/replay expectations, operational capability, and infrastructure cost.

Option evaluation:

Criterion	REST (sync)	Queue (RabbitMQ)	Event log (Kafka)
Decouples availability
At-least-once delivery
Retention / replay capability
Independent consumers
Team can operate today
Infra cost	low	medium	high
Note	Simplest runtime path, but the caller stays tightly coupled to inventory availability.	Fits the current requirements. Retention, replay, and fan-out depend on queue topology, persistence, and operating choices.	Stronger fit when longer retention, replay, or multiple independent consumers become core requirements and the team can operate it.

Click a column to highlight. met partial not met

The replay row is about technical capability: how naturally the option supports retaining and re-consuming past messages. That is not the same as abusiness audit trail. Compliance or audit requirements may also need immutable retention policies, schema governance, access controls, and evidence about who produced or consumed the record.

Decision for this context: RabbitMQ is the better fit now because it satisfies the team's core delivery and decoupling requirements without demanding a heavier operational model. If the system later needs longer retention, more independent consumers, or replay as a first-class capability, the trade-off can shift toward Kafka.

ADR change trigger: "Revisit if more than one independent consumer needs order events, or if longer retention/replay becomes a real requirement. At that point the event-log option may be justified despite the higher operating cost." Whether RabbitMQ can meet a replay need depends on version and configuration (for example, streams or quorum queues), so check the current docs before treating this comparison as fixed.

Trade-offs

What you are actually weighing

Reversible vs harder-to-reverse

Messaging choices can look easy to undo early, then harden as data accumulates, consumers multiply, and external contracts form. Judge reversibility by migration cost and blast radius, not by day-one optimism.

Criteria selection bias

Agreeing criteria before seeing the options prevents post-hoc rationalisation. Teams that pick criteria after exploring options unconsciously weight the ones their preferred choice scores well on.

Operational capability vs technical capability

A technology you cannot operate safely is worse than a technically stronger one you can. A Kafka cluster at 2am requires engineers who understand consumer lag, partition rebalancing, and offset management.

Decision speed vs decision quality

High-blast-radius decisions justify slowing down and consulting broadly. Bounded, reversible decisions should move faster; over-analysing them creates its own delivery cost.

What Can Go Wrong

Decision-making failure modes

🎯Solution-first framing

"We need Kafka" before the problem is defined. Option space collapses before exploration begins.

📊Post-hoc criteria

Criteria chosen after seeing options. Team unconsciously weights what their preferred option scores well on.

⏰No change trigger

Decision was right at Stage 2. System is now at Stage 8. Nobody recorded when to revisit it.

📝Missing rejection reasoning

ADR says "we chose X" but not "we rejected Y because Z." Future engineers re-evaluate from scratch.

🔄Reversibility frozen in time

Team assumes a once-reversible decision is still easy to change, ignoring new consumers, contracts, and migration cost.

🚧Capability ignored

Team selects the technically stronger option they cannot operate. Correct on paper; wrong in production at 2am.

When To Use / When Not To Use

Calibrating rigour to decision type

✓ Full ADR when decision is

→ Costly to reverse because of contracts, data, or adoption
→ Affects multiple teams or downstream systems
→ A long-term platform commitment
→ Likely to be questioned or revisited later

⚡ Lightweight record when

→ Reversal cost is genuinely small today
→ Blast radius is limited to a single team
→ A quick spike can validate the choice
→ Speed of decision matters more than precision

Architect's Challenge

You're choosing between REST, a queue, and Kafka for inter-service communication. What should you agree on BEFORE evaluating any option?

Remember· 30-second mental model

Frame the problem first. Agree criteria before evaluating options. Record the decision — and the reasoning behind the rejections.

1The problem statement determines the option space — frame it at the requirement level, not the solution level.
2Agree evaluation criteria before exploring options to avoid post-hoc rationalisation.
3Treat reversibility as a spectrum shaped by data gravity, contracts, adoption, and migration cost.
4Rejected alternatives are often the part of the ADR future engineers most need later.
5Every ADR needs a change trigger and, when relevant, a status or supersession note.

Key lesson

An ADR is not just the answer. It is the reasoning, assumptions, consequences, and revisit trigger that keep the answer useful later.