Module 1: What an Architect Really Does

Reversible over right

Overview

Lessons 2 and 3 removed two things the architect is not: not the one who draws the perfect blueprint and leaves, nor the one who decides from the penthouse without going down to the code. This lesson answers the positive question: so, what is their product? What does an architect who does their job well deliver? The answer defies intuition. The architect's product isn't "the right decision". It's a decision whose error is cheap —a reversible decision— accompanied by the why recorded so it can be revised. In one word: the architect doesn't sell certainties; they sell options that can be undone.

This sounds almost like heresy in a role that's asked to "get it right". But it's the direct consequence of the two previous lessons. If the day-one diagram is a hypothesis that gets 70% redone (lesson 2), and if any estimate under uncertainty can fail (lesson 3), then betting everything on getting it right is betting against reality. The mature architect accepts they'll be wrong part of the time —it's inevitable with incomplete information— and shifts their effort from "reducing the probability of being wrong" to "reducing the cost of being wrong". A decision you can undo cheaply lets you be wrong without it hurting; one that ties you down turns every error into a catastrophe. This lesson measures it: it compares two stances —betting on getting it right vs. betting on being able to undo— over uncertain Mercado decisions, and shows why, when uncertainty is high, making the error cheap wins by a landslide.

Connection with the module. It's the first of the three lessons that define the real architect by what they do (this one: they make expensive decisions reversible and communicate the why; lesson 5: they enable; lesson 6: they don't become a bottleneck). Here we install their central product. Watch the frontier, because it's the most delicate of the module: the mechanics of reversibility —how to classify a decision as a one-way or two-way door, how to compute the last responsible moment, how to structure a decision to keep it open— is the sister guide architecture-decisions-and-tradeoffs (its module 7). Here we do not re-teach that mechanics; we work the stance of the role: why the architect understands their deliverable is a decision cheap to undo plus its why, and not a definitive verdict. The technique is the other guide's; the professional identity that uses it is this guide's.

An analogy: renting before buying in a new city

You move to a city you don't know and have to decide where to live. There are two ways to approach that decision, and they're two philosophies of the role.

Betting on getting it right (buying right away). You invest weeks researching: crime maps, commute times, school quality, price trends. With all that information you buy a house in the first month. You did your homework, you chose rigorously. But the city has things no map tells you: that that "quiet" neighborhood is unbearable on weekends because of a bar, that the commute the map says is 20 minutes is 50 at rush hour, that three blocks away there's construction that will last two years. If you were wrong —and with incomplete information it's likely—, undoing the purchase is very expensive: selling, losing on commissions, moving again. You bet everything on getting it right, and when reality contradicts you, you pay dearly.

Betting on being able to undo (renting first). You rent for six months in a neighborhood that seems good, without the exhaustive research. You live the city for real: you feel the weekend bar, you suffer the real traffic, you see the construction. If the neighborhood wasn't it, you move when the lease ends —low cost, bounded hassle—. And when you finally buy, you buy with information no map would have given you, because you lived it. You didn't bet on getting it right in the first month; you bet on making being wrong cheap, and used that margin to learn.

Here's the point: whoever rents first is wrong more often, but each mistake costs them little; whoever buys right away is wrong less often, but each mistake costs them a fortune. With a city you don't know —high uncertainty— the second strategy wins almost always, because the total cost isn't dominated by how many times you're wrong, but by how much each time costs. The real architect is the one who rents first: facing orders→shipping, facing extracting the catalog, facing the second payments provider —all decisions in a city they don't fully know— they prefer the option they can undo cheaply over the one that ties them down, even though the tying one "sounds" more definitive. This lesson puts a number on that intuition.

Worked example: betting on getting it right vs. betting on being able to undo

We compare two architect stances over four uncertain Mercado decisions. In each decision there's a real probability of being wrong (p_wrong), because the information is incomplete —it's the city you don't know—:

aim_right — the "I'm going to get it right" stance: it invests a lot of upfront analysis (which halves the probability of failing, but not to zero) and commits hard. If it still fails, reverting is very expensive because it got tied down.
aim_reversible — the real architect's stance: decide fast, without much analysis, but keeping a cheap exit. If it fails, revert cheaply.

# The real architect's product isn't "the right decision"; it's a decision
# whose ERROR is cheap (reversible) + the recorded why. We compare two
# stances over 4 uncertain Mercado decisions:
#   aim_right      : invests a lot of analysis to get it right and commits hard;
#                    if it still fails, reverting is very expensive.
#   aim_reversible : decides fast keeping an exit; if it fails, reverts cheaply.
# p_wrong = probability of being wrong (the uncertainty is real and high).
DECISIONS = [
    # (id, p_wrong, revert_if_locked_in, revert_if_reversible, analysis_cost)
    ("async_orders_to_shipping", 0.40, 60000, 6000, 12000),
    ("extract_catalog_service",  0.35, 90000, 9000, 15000),
    ("second_payments_provider", 0.30, 40000, 4000,  8000),
    ("event_bus_vs_direct_call", 0.45, 50000, 5000, 10000),
]

print(f"{'decision':<28}{'aim_right':>12}{'aim_reversible':>16}")
print("-" * 56)
tot_right = tot_rev = 0
for did, p, lock_cost, rev_cost, analysis in DECISIONS:
    # aim_right: pays the analysis always; the analysis halves the prob of
    # failing, but if it still fails, the reversion is very expensive (tied down).
    cost_right = analysis + (p / 2) * lock_cost
    # aim_reversible: almost no analysis; if it fails, reverts cheaply.
    cost_rev = p * rev_cost
    tot_right += cost_right
    tot_rev += cost_rev
    print(f"{did:<28}{cost_right:>12,.0f}{cost_rev:>16,.0f}")

print("-" * 56)
print(f"{'TOTAL expected cost (USD)':<28}{tot_right:>12,.0f}{tot_rev:>16,.0f}")
print()
print("aim_right pays analysis upfront AND stays exposed to a very expensive")
print("reversion when it fails. aim_reversible accepts it will fail sometimes,")
print("but makes failing cheap. With high uncertainty, cheapening the error")
print("wins. The architect doesn't sell certainties; they sell options you can undo.")

What to expect. Running the file, the output is exactly this:

decision                       aim_right  aim_reversible
--------------------------------------------------------
async_orders_to_shipping          24,000           2,400
extract_catalog_service           30,750           3,150
second_payments_provider          14,000           1,200
event_bus_vs_direct_call          21,250           2,250
--------------------------------------------------------
TOTAL expected cost (USD)         90,000           9,000

aim_right pays analysis upfront AND stays exposed to a very expensive
reversion when it fails. aim_reversible accepts it will fail sometimes,
but makes failing cheap. With high uncertainty, cheapening the error
wins. The architect doesn't sell certainties; they sell options you can undo.

Read the two totals, because the difference is the lesson's whole argument: 90000 expected dollars betting on getting it right, against 9000 betting on being able to undo. An order of magnitude. Ten times more expensive to try to get it right than to make the error cheap. Let's break down why.

The aim_right stance pays twice. First it pays the upfront analysis —12000, 15000, 8000, 10000 dollars of research to "get it right"— and it pays it always, whether you're right or not. Second, even after all that analysis, it stays exposed to the very expensive reversion when it fails, because it committed hard. In async_orders_to_shipping: 12000 of analysis + a 20% probability of failing (analysis halved the original 40%) times 60000 to revert tied down = 24000. The analysis reduced the probability of error, but didn't eliminate it, and when the error arrives, the tied-down cost is brutal.

The aim_reversible stance pays almost no analysis —it decides fast— and when it fails, it reverts cheaply: in async_orders_to_shipping, a 40% probability of failing times only 6000 to revert = 2400. It's wrong more often than aim_right (40% vs. 20%, because it didn't invest in reducing the probability), but each mistake costs it a tenth. And there's the heart: the total cost isn't dominated by how many times you're wrong, but by how much each time costs. aim_reversible accepts being wrong twice as often and still wins ten to one, because it attacked the variable that matters —the cost of the error— instead of the one that impresses —the probability of the error—.

Notice what this tells the architect about their identity. The culture asks them to "get it right", and they learn to redefine their work: not as "making the right decision" —an impossible goal with incomplete information— but as "structuring the decision so being wrong comes out cheap". That changes everything they do: instead of three weeks of committee to choose between synchronous and events, they set up the option they can change later and move forward; instead of tying Mercado to a "perfect" payments provider, they choose one they can swap. Their product isn't a verdict; it's a door that stays open plus the record of why they went through it this way, so whoever comes after can close it or open another.

As bars, the landslide is visible:

Total expected cost (USD): getting it right vs. being able to undo
 aim_right       |##################################  90,000
 aim_reversible  |###                                  9,000
                  ─────────────────────────────────
 10x more expensive to bet on getting it right than on cheapening the error.

Deep dive: why the why travels with the decision

The architect's product has two parts, and so far we've focused on the first —the reversible decision—. The second is just as important: the why. A reversible decision without its why is half a delivery, and it's worth understanding why the real architect never delivers one without the other.

Think about what happens six months after making the orders→shipping decision. The architect who made it may no longer be in that meeting, may have changed projects, may have left the company. A new squad arrives, sees the decision —"orders calls shipping synchronously, with this exit prepared in case we need to switch to events"— and has to decide whether to keep it, revert it, or evolve it. If all they inherited is what was decided, they're blind: they don't know what alternatives were considered, what was known and what wasn't, what would make it revisable. They may well revert a decision that was good, or keep one that no longer applies, because they lack the context. The what without the why condemns those who come after to repeat the analysis from scratch, or worse, to decide blind.

That's why the real architect makes the why travel with the decision through time. They record: what was decided, what alternatives were weighed, what was known and what wasn't (the honest fog), and under what conditions it would need to be revisited. That record is what lets a reversible decision be reverted with judgment months later, instead of on a hunch. Reversibility opens the door; the why tells whoever comes why it's open and when it's worth going through it in another direction.

The formal vehicle of that why is the ADR —Architecture Decision Record—, and here we must be precise about the ecosystem's frontier. The mechanics of the ADR (its Context/Decision/Consequences/Status structure, how to write it, how to version it) is taught by the sister guide architecture-decisions, and its communicative use in depth —the ADR as a piece different audiences understand— is module 3 of this guide. Here we only install the principle of the role: the architect doesn't deliver decisions orphaned of their why. A decision without its reason recorded is a trap for the future, however reversible it is, because no one will know when or why to revert it. The architect's complete product is the open door and the map of why it's where it is.

A liberating consequence of the role. Defining the product as "reversible + why" instead of "right" takes an impossible weight off the architect. No one can guarantee getting it right under uncertainty; everyone can structure their decisions so being wrong comes out cheap and leave the why recorded. The first standard produces architects paralyzed by the fear of being wrong (who fall into paralysis and BDUF); the second produces architects who move forward, learn, and correct. The maturity of the craft isn't being wrong less; it's having designed things so that being wrong isn't catastrophic. The architect who internalizes this stops needing to be right —a need that, as we'll see in lessons 5 and 6, is the root of the dictator and the bottleneck— and starts building systems and teams that survive being wrong.

Common mistakes

Chasing the "right" decision and freezing. What happens: the architect treats every decision as if they had to get it right, invests weeks of analysis seeking certainty, and meanwhile the squads wait and the system doesn't move. Why it happens: the culture asks them to "get it right" and they internalize it as their standard, without noticing certainty doesn't exist with incomplete information —chasing it is chasing a horizon—. How to spot it: if a decision has been "in analysis" for weeks without its uncertainty dropping, or if the architect won't commit "until they're sure", they're betting on getting it right in a city they don't know. How to fix it: redefine the product —from "the right decision" to "a reversible decision plus its why"— and ask yourself, facing each decision, not "which is the right one?" but "which can I undo cheaply if I'm wrong?". That unblocks progress without betting the house. (The formal calculation of how much to analyze before deciding is the sister guide; here the stance is enough.)

Tying the system down in search of the "definitive" option. What happens: the architect chooses the solution that "sounds" most complete and permanent —a single, perfect payments provider, a synchronous integration "because it's simpler"— and in the process leaves the system with no cheap exit if that option turns out bad. Why it happens: definitive options feel more professional and decisive than tentative ones; "leaving a door open" can seem like indecision. How to spot it: if on asking "and if this turns out bad, how much does it cost to change it?" the answer is "very expensive, we'd be tied down", the architect optimized for definitiveness instead of reversibility. How to fix it: prefer, between two options of similar merit, the one that keeps a cheap exit, even if it's a bit less "elegant". The example quantifies it: the tied-down reversion (60000, 90000) is what makes aim_right ten times more expensive. An open door is worth more than a decision that looks definitive.

Delivering the decision without its why. What happens: the architect makes a decision —even a reversible and good one— but only communicates the what ("orders calls shipping synchronously"), without recording the alternatives, what was known, or when to revisit it; months later no one understands why it's this way, and it's reverted blind or kept out of inertia. Why it happens: the why lives in the architect's head at the moment of deciding, and feels obvious, so it isn't recorded —until the architect leaves or forgets it—. How to spot it: if on asking the squad "why is this this way?" the answer is "I don't know, it was already there" or "that's how the previous architect decided it", the why didn't travel with the decision. How to fix it: treat recording the why as an inseparable part of the product —a decision without its reason isn't finished—. The ADR is the vehicle (its mechanics is the sister guide; its communicative use, module 3), but the principle of the role is this: don't deliver open doors without the map of why they're open.

Exercises

Exercise 1 — Reframe the decision. The VP asks the architect for "the right decision" on whether Mercado adopts a second payments provider. Instead of launching into a three-week analysis to "get it right", how would the real architect reframe this decision, and what would they ask to structure it as reversible?

See solution

The real architect doesn't seek "the right one"; they seek "the one I can undo cheaply if I'm wrong". They reframe the question from "one provider or two?" to "how do I structure payments to be able to change my mind without it hurting?".

The questions they'd ask to make it reversible: can we put an abstraction layer over the payments provider, so that adding or removing one is a bounded change and not a rewrite? Can we start with one provider but design the integration so that adding the second later costs little? What information are we missing —how much does the single provider really go down, what volume justifies the second— and can we get it cheaply before tying ourselves down?

With that reframe, the delivery to the VP isn't "the definitive answer after three weeks", but something like: "we start with one provider, but with the integration structured so adding the second costs little if we need it; that way we move forward now, and if reality tells us the second is needed, we add it cheaply". The architect delivered them an open door, not a verdict —and saved them three weeks of analysis to get right something reversibility makes unnecessary to get right the first time—. (How to design that abstraction layer is a technical guide; that the architect seeks it as a stance is this lesson.)

Exercise 2 — When getting it right does matter: the one-way door. The example shows that betting on being able to undo wins ten to one. Does that mean the architect should never invest in analysis to get it right? Describe the kind of decision where aim_right would make sense, and why.

See solution

No, it doesn't mean analysis is never worth it. aim_reversible's landslide depends on an assumption of the example: that the decision can be made cheaply reversible (reverting costs 6000 instead of 60000). When that's true, betting on undoing wins. But there are decisions that are intrinsically irreversible —the "one-way doors"— where no cheap exit exists no matter how you search: splitting Mercado's single database into one per service, for example, or a decision that exposes a public contract to thousands of external clients who will then depend on it.

In those decisions, aim_reversible isn't available —there's no door to leave open— so the architect should invest in getting it right: deep analysis, spikes, committees if needed. The rigor should be proportional to the irreversibility. What the lesson teaches isn't "never analyze", but "first ask if you can make it reversible; if so, make it reversible and move forward cheaply; if it's genuinely one-way, then do invest in getting it right". The mistake is applying the rigor of a one-way door to a decision that was two-way —analyzing for three weeks something you could have left open and changed in a day—.

(The formal distinction between one-way and two-way doors, and how to classify them, is exactly module 7 of the sister guide architecture-decisions. Here it's enough that the architect knows their first question is "can I make this reversible?", and only if the answer is no, they bet on getting it right.)

Exercise 3 — The why that didn't travel. A new Mercado squad inherits this decision: "orders publishes an OrderPlaced event and shipping consumes it, instead of a direct call". There's no record of why. The squad, which values simplicity, is about to revert it to a direct synchronous call "because it's simpler". Explain what was lost by not recording the why, and what that record should have contained to avoid this blind reversion.

See solution

What was lost is the context that made the decision good. The new squad sees the what (events instead of direct call) but not the why, so it judges the decision only by its current criterion (simplicity) without knowing what problem it solved. It's quite possible it's about to revert a correct decision: maybe events were chosen precisely because the direct synchronous call took down checkout when shipping went down (the problem lesson 2 mentioned). If it reverts without knowing this, it will reintroduce that fragility and rediscover the problem the hard way, months of work later.

That record should have contained: what was decided (events), what alternatives were weighed (direct synchronous call, which is exactly what the squad wants now), why the alternative was discarded (the synchronous one coupled the checkout's availability to shipping's; if shipping went down, the orders went down), what was known and what wasn't at that moment, and under what conditions it would make sense to revisit it (for example, "if shipping reaches such-and-such availability, reconsider"). With that record, the new squad doesn't revert blind: it sees that the simplicity it seeks was already considered and discarded for a good reason, and decides with judgment —or finds that conditions changed and reverts it knowing what it's doing—.

That's exactly the meaning of "the why travels with the decision": a reversible decision without its record isn't an advantage, it's a trap, because anyone can undo it without understanding what held it up. The architect's product wasn't complete with just choosing events; it lacked the map of why. (The format of that record —the ADR— is the sister guide and module 3; the principle of not delivering orphaned decisions is this lesson.)

Summary and next step

In this lesson you defined the real architect's product, and it isn't the one the culture asks for. It's not "the right decision" —an impossible goal under uncertainty— but a decision whose error is cheap (reversible) plus the why recorded so it can be revised with judgment. You saw, with renting before buying, that whoever bets on being able to undo is wrong more often but pays little each time, and beats whoever bets on getting it right. And you measured it: betting on getting it right costs 90000 expected dollars against 9000 for betting on being able to undo —ten to one— because the total cost is dominated by how much each error costs, not by how many errors there are. The architect doesn't sell certainties; they sell options that can be undone, with their why.

Before moving on you should be able to: explain why "reversible + why" is a better standard than "right" under uncertainty; reframe a decision from "which is the right one?" to "which can I undo cheaply?"; recognize when a decision is intrinsically irreversible (one-way door) and does deserve the effort to get it right; and argue why a reversible decision without its why recorded is a trap for the future.

Lesson 5 continues with the second verb of the real architect. You now know they make expensive decisions reversible (this lesson); now you'll see that they enable the team. The real architect isn't a dictator who decides for the squads; they're a gardener who sets guardrails —clear limits— and returns the local decision to whoever is closest to the problem. With numbers: how many decisions from a typical Mercado week the squads can resolve alone when the architect enables instead of dictating.

Resources

Jeff Bezos, Amazon Shareholder Letter (2015) — sec.gov/Archives/edgar/data/1018724/000119312516530910/d168744dex991.htm. The origin of "one-way and two-way doors": irreversible decisions deserve deliberation; reversible ones, speed. The basis of this lesson's stance. Its mechanics is worked in the sister guide architecture-decisions. In English.
Mark Richards and Neal Ford, Fundamentals of Software Architecture, 2nd ed. (O'Reilly, 2020), ch. 19 "Architecture Decisions" — on why significant decisions are measured by their cost of change, and why the architect thinks in reversibility. In English.
Martin Fowler, "Who Needs an Architect?" (IEEE Software, 2003) — martinfowler.com/ieeeSoftware/whoNeedsArchitect.pdf. Contains the idea that the architect's work is, in good part, keeping the important decisions easy to change as long as possible. In English.
Michael Nygard, "Documenting Architecture Decisions" (2011) — cognitect.com/blog/2011/11/15/documenting-architecture-decisions. The post that originated the ADR, the vehicle of the "why that travels with the decision". Its format is worked in module 3 and the sister guide. In English.

← PreviousThe architect stays close to the code Next →Enabling, not dictating