Decision Making and ADRs
A DabbaGo engineer finds that kitchen payouts go through a slow nightly batch instead of paying each kitchen right away. It looks like a mistake, so she spends a week making it real-time. Then finance explains: the bank charges a fee per transfer, so one batch a night saves lakhs of rupees a year. The original reason was never written down. A decision without its reason is a trap waiting for the next person.
The rule
Compare real options, choose one, and write down why.
Good architectural decisions share three habits:
- Real options. At least two genuine alternatives, including "do nothing" when it is honest. A decision with one option was never really a decision.
- Forces. The pressures that make the choice hard: quality attribute scenarios, deadlines, budget, team skills, rules. Options are judged against forces, not against taste.
- A record. The decision, its context and its consequences, written where the team will find it.
The standard record is an Architecture Decision Record (ADR): a short file, often kept in the repository next to the code. A common shape:
ADR 12: Pay kitchens in one nightly batch
Status: Accepted
Context:
The bank charges a fee on every transfer. 1,200 kitchens are paid daily.
Kitchens told us next-morning payment is fine.
Decision:
Pay all kitchens in one batch at 11 pm.
Consequences:
+ Transfer fees drop sharply.
- A kitchen cannot be paid instantly, even in an emergency.
- If the batch fails, every kitchen is paid late; we need an alert.Two rules keep ADRs useful. Consequences include the downsides; an ADR that lists only benefits is a sales pitch. And accepted ADRs are not edited to reverse them. When a decision changes, write a new ADR that supersedes the old one, and mark the old one "Superseded by ADR 19". The history of why things changed is as valuable as the current state.
The shortcut
Before deciding, fill in one line: "We chose X over Y because of Z, accepting W." If you cannot name Y, you have not compared options. If you cannot name W, you have not looked for the cost.
List real options
Option A: the rider app asks the server every 30 seconds. Option B: the server pushes each job instantly.
The trap is writing the ADR after the fact to justify a choice already made, with the alternatives invented to look weak. Write it while the options are still open.
Drills
Answer fast — trust the rule.
What was missing when the engineer "fixed" the nightly payout batch?
Which part of an ADR should list the downsides of the decision?
DabbaGo later decides to pay kitchens instantly after the bank drops its fee. What happens to ADR 12?
Someone writes "We chose PostgreSQL because it is good." What does the shortcut line show is missing?
Remember
- Compare real options against the forces, choose one, and write down why in an ADR.
- Shortcut: "We chose X over Y because of Z, accepting W."
- Traps: ADRs with no downsides, and editing old ADRs instead of superseding them.