Architecture decisions and ADRs · Prasanta Kumar Behera

Make architecture decisions that hold up: frame the problem and the criteria, compare real options, decide at the right speed for how reversible the choice is, write it down as an ADR, and know how to disagree and then commit.

A shape for good decisions

Problem and context: what are we solving, for whom, and what constraints apply (scale, compliance, team skills, deadline)?
Decision criteria: agreed before comparing options (reliability, operability, cost, time to deliver, lock-in, security).
Options: at least two real ones, including "do nothing" or "the boring option".
Trade-offs: score options against the criteria; say what each makes worse.
Decision and reasons, for this context.
Consequences: what we now have to do, what we're giving up, what would make us revisit it.

Choosing an architecture is like choosing a family car. First agree what matters (seats, boot size, running cost), then look at cars. If you look at cars first, everyone falls in love with a different one and argues about colours.

Decide at the right speed

Decision	Example	Process
Two-way door (cheap to reverse)	A Helm chart structure, a dashboard layout, a library inside one service	The people doing the work decide; note it briefly
One-way door (expensive to reverse)	CNI, cluster topology, IP plan, identity model, GitOps tool, a public API	Written proposal, design review, ADR, sign-off from the people who'll live with it

Most decisions are two-way doors; treating them as one-way slows everyone down.

Write it down: the ADR

ADR-012: Gateway API as the standard ingress for new services

Status: Accepted (2026-03-14)

Context
  Three ingress controllers in use; teams copy annotations between them; no shared gateway;
  canary releases need weighted routing.

Options
  1. Keep NGINX Ingress everywhere (familiar; annotations not portable; limited role separation)
  2. Gateway API with a shared, platform-owned Gateway (role separation, weights, portable; newer)
  3. A service mesh ingress (powerful; adds a mesh we don't otherwise need)

Decision
  Option 2 for all new services; existing Ingresses migrate when touched.

Consequences
  Platform team owns Gateways and policies; teams own HTTPRoutes.
  Need runbooks and a migration guide. Revisit if the controller lacks a feature we need.

Keep ADRs in the repository they affect, numbered, never deleted (superseded ADRs link to their replacement).

Design reviews that help

Review early (a one-page proposal), not after the code is written.
Invite the people who will operate it, not only those who will build it.
Ask "what would make this fail?" and "what's the simplest version that works?".
End every review with a clear outcome: approved, approved with changes, or needs another round, and who decides.

Disagree, then commit

Before the decision: argue your case with evidence, offer alternatives, and make sure your concern is understood (ask someone to restate it). After the decision: support it fully, help it succeed, and keep watching. If new evidence appears, raise it with the data, not with "I told you so".

Try it: write three ADRs

Pick a decision your team made recently without writing it down; write the ADR from memory and ask whether others agree with the recorded context.
Pick an open question (e.g. "Argo CD or Flux?") and write a proposal with criteria agreed first, then options and trade-offs.
Classify the last ten technical decisions as two-way or one-way doors; were the slow ones the right ones?
Run a 30-minute design review on the proposal using the questions above.
Create a docs/adr/ folder with a template in your platform repository.

Going deeper: decisions at scale

For decisions affecting many teams, use a lightweight RFC process with a comment period and a named decider.
Track decision debt: important questions left open too long cost more than a wrong-but-reversible answer.
Review old ADRs yearly; mark the ones whose context has changed.

Recap

Agree criteria before comparing options; always state the trade-offs.
Match the process to reversibility: quick for two-way doors, careful for one-way doors.
Record decisions as ADRs: context, options, decision, consequences.
Disagree with evidence before; commit fully after; reopen only with new evidence.

This site is a public version of my personal engineering knowledge hub. It intentionally excludes confidential company information and internal operational details.