Module 1: What an Architect Really Does

The architect stays close to the code

Next →

Overview

Lesson 2 left a consequence hanging: if the architect has to be on the site to correct the blueprint, they have to be able to go down to the site. In software, the site is the code. This lesson attacks the second false image of the role: the architect who thinks themselves too senior to touch code, who lives in the meetings, the slides, and the diagrams, and who decides about the system they remember instead of the one that exists. It's an especially damaging image because it sounds like maturity —"I got promoted, I don't program anymore"— when in reality it's the beginning of technical irrelevance.

The metaphor that organizes this lesson is Gregor Hohpe's: the architect elevator. A building has a penthouse —the top floor, where the business is: the stakeholders, the strategy, the budget— and a machine room —the basement, where the code is: the services, the databases, the bugs, what actually runs—. The architect doesn't live on either floor; their job is to run the elevator that connects them: go up to translate the business into technical attributes, and go down to see how the machine room can (or can't) meet them. The architect who stays up top, in the penthouse, loses contact with the machine and starts deciding on an old mental model. This lesson measures what happens to the quality of their decisions —specifically, to their estimates— as they detach from the code.

Connection with the module. It's the direct correction of the ivory tower (lesson 2): being present on the site requires going down to the code, and this lesson explains how and why. It also sets up everything that follows: an architect glued to the code makes more reversible decisions because they know the real cost of undoing them (lesson 4), enables better because they understand the squads' work (lesson 5), and avoids BDUF because they sense when the information isn't mature yet (lesson 7). Watch the nuance, because it's easy to misread: "close to the code" does not mean the architect is the one who writes the most code —that would turn them into a different bottleneck, the one in lesson 6—. It means they keep sufficient and regular contact so their mental model matches reality. They code differently, not necessarily less.

An analogy: the chef who stopped going into the kitchen

Think of a chef who opened a restaurant and succeeded. At first they cooked every dish. With growth, they hired cooks, and their role changed: now they design the menu, choose suppliers, train the team, talk to the important customers. Up to here, healthy —it's exactly the architect going up to the penthouse—.

But there are two possible chefs from that point on.

The chef who stopped going into the kitchen. They settled into the dining room and the office. They design the menu from their desk, based on how they remember the kitchen working three years ago. They promise an important customer a new dish "for Friday" without having set foot in the kitchen in months: they don't know the old oven takes twice as long, that the seafood supplier changed, that two new cooks haven't yet mastered the technique that dish demands. Their promise is unreal, and the kitchen breaks trying to keep it. Their decisions are prettier and prettier on paper and more and more impossible in practice, because they make them about a kitchen that no longer exists.

The chef who keeps going down to the kitchen. They also design the menu and talk to customers —they also live in the dining room—, but they go down to the kitchen regularly. They taste the dishes, see the old oven, know the new cooks, know which supplier is failing this week. When they promise a dish "for Friday", the promise is real, because their model of the kitchen is up to date. They don't cook every dish —that would make them a bottleneck—; they go down enough for their head to match the reality of the fire.

The first chef lives in the penthouse. The second runs the elevator. And the difference shows, above all, in their promises and estimates: the one who doesn't go down promises things the kitchen can't deliver, and finds out late and expensive; the one who goes down promises what the kitchen can, and gets it right. The software architect is the chef. The kitchen is the code. And this lesson measures, in Mercado, how much an architect's estimate detaches from reality as they stop going down to the machine room.

Worked example: how the estimation error grows with distance from the code

When a Mercado squad proposes a change, someone has to estimate how much effort it costs —to prioritize, to promise the business, to plan—. The architect is often the one who gives or validates that estimate. This lesson's question is: how good is their estimate depending on how close they are to the code?

We take four real Mercado changes with their real effort in days (measured afterward, once done). Then we model an architect's estimate at different distances from the code: 0 = programs in the repo this very week, 5 = only sees slides and never opens the code. The idea, well documented in practice, is that the farther from the code, the more optimistic (unrealistically) the estimate becomes —from the penthouse everything "looks easier" than it is down below—:

# The "architect elevator" (Hohpe): go up to the penthouse (business) and down
# to the machine room (code). Here we measure what happens when an architect
# stays UP: their effort estimate detaches from the reality of the code.
# code_distance: 0 = programs in the repo this week; 5 = only sees slides.
# For 4 real Mercado changes we have the REAL effort (days) and estimate
# an architect's error at each distance (farther = more underestimation).
CHANGES = [
    # (change, actual_days)
    ("add_idempotency_to_payments", 8),
    ("split_catalog_read_model",    13),
    ("async_orders_to_shipping",    21),
    ("cache_catalog_hot_path",      5),
]


def estimate(actual_days, code_distance):
    # Each level of distance from the code inflates optimism ~18%: from the
    # penthouse everything "looks easier" than it is in the machine room.
    optimism = 1 - 0.18 * code_distance
    return max(1, round(actual_days * optimism))


avg_actual = sum(a for _, a in CHANGES) / len(CHANGES)
print(f"{'code_distance':>13}{'avg_error_days':>16}{'avg_error_pct':>15}")
print("-" * 44)
for distance in range(0, 6):
    errors = [abs(estimate(actual, distance) - actual) for _, actual in CHANGES]
    avg_err = sum(errors) / len(errors)
    pct = round(100 * avg_err / avg_actual)
    print(f"{distance:>13}{avg_err:>16.1f}{pct:>14}%")

print()
print("At distance 0 (touches the code this week) the architect is right; at")
print("distance 5 (slides only) they're off by more than half the effort.")
print("That's why the real architect takes the elevator down to the machine room.")

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

code_distance  avg_error_days  avg_error_pct
--------------------------------------------
            0             0.0             0%
            1             2.0            17%
            2             4.5            38%
            3             6.2            53%
            4             8.5            72%
            5            10.5            89%

At distance 0 (touches the code this week) the architect is right; at
distance 5 (slides only) they're off by more than half the effort.
That's why the real architect takes the elevator down to the machine room.

Read the right-hand column top to bottom, because it's the price of living in the penthouse.

At distance 0 —the architect touches the code this very week, knows the real state of the payments database, knows how the catalog is doing— their error is 0%. They estimate well because their mental model is the reality. There's no magic: when you know the kitchen, you know how long the dish takes.

As the distance goes up, the error grows, and not slowly. At distance 2 —the architect who reviews PRs now and then but doesn't touch the code— they're already off by 38%: a change that takes 13 days they estimate at 8, and the squad inherits an impossible promise. At distance 5 —the architect who only sees slides, who hasn't opened the repository in months, who decides about the Mercado they remember— the error is 89%: they estimate async_orders_to_shipping takes 2 days when it takes 21. It's not that they're dumb; it's that their kitchen is imaginary. From the penthouse, moving orders to asynchronous communication "looks like" a config change; in the machine room it's rewriting how two services talk, with everything that drags along.

Notice the nature of the error: it's always optimistic underestimation. The architect detached from the code doesn't err at random —sometimes over, sometimes under—; they err systematically downward, promising things are easier than they are. This has a serious organizational consequence: their promises to the business are unreal, the squads are trapped between an impossible date and an architect who "already estimated it", and when the change takes what it really takes, the blame falls on whoever builds, not on whoever estimated badly from above. The penthouse promises; the machine room pays.

And here's the reading that gives the lesson its name: the quality of the architect's decisions is a function of their distance from the code. Not of their seniority, not of their title, not of how pretty their slides are. Of whether they take the elevator down. A brilliant architect at distance 5 makes worse decisions than an average one at distance 1, because the brilliant one decides about a system that no longer exists. Contact with the code isn't a nostalgic luxury of the architect who "misses programming"; it's the data source without which their decisions float.

As bars, the detachment shows clearly:

Estimation error by distance from the code (89% = almost 9x error)
 dist 0 |                          0%   (touches the code: right)
 dist 1 |####                     17%
 dist 2 |#########                38%
 dist 3 |#############            53%
 dist 4 |##################       72%
 dist 5 |######################   89%   (slides only: almost all error)

Deep dive: what "close to the code" means without becoming the bottleneck

Here's a real tension to resolve carefully, because this module teaches two things that seem to contradict each other: lesson 3 says "stay close to the code" and lesson 6 will say "don't be the bottleneck everything passes through". How do the two hold at once? The answer is in what kind of contact with the code the architect keeps.

Close to the code does NOT mean being the one who writes the most code. If the architect authors half the commits, or if every technical decision waits for them to implement the hard part, they became the bottleneck —they code so much that the squads depend on them to move forward—. That's as damaging as the penthouse, only from the other extreme. The architect who writes all the critical code concentrates the knowledge in their head (the bus factor we'll see in module 7) and blocks everyone.

Close to the code DOES mean keeping the mental model up to date. There are many ways to take the elevator down without becoming the funnel:

  • Read code regularly. Not writing everything, but reading the parts that matter: how the new catalog service turned out, how orders handles retries, where the fragile points are. Reading keeps the model fresh without blocking anyone.
  • Review PRs selectively. Not every PR (that's the lesson 1 bottleneck), but the ones that touch architect-level decisions: the contract between orders and shipping, a change in shared authentication. Reviewing the few that matter gives real contact with the code without slowing the squads.
  • Do a spike now and then. When there's a big decision with technical uncertainty —"how much does it really cost to move orders to async?"—, the architect can go down to build a small prototype, with their own hands, to feel the real cost. It's the best cure against optimistic estimation: you don't guess how long the dish takes; you cook it once.
  • Sit with the squads on their ground. Occasional pair programming, being in the technical design sessions, seeing the problems where they occur. The architect who sits half an hour with the payments squad to look at the real integration code learns more than ten status meetings would tell them.

The practical test: does your estimate sound credible to the squad? A quick way to know how far away you are: when you give an estimate or describe how the system is, does the squad nod or exchange glances? If the engineers who touch the code daily feel your model of the system is real, you're taking the elevator down enough. If they feel you're talking about a Mercado that no longer exists —"we changed that six months ago"—, you're living in the penthouse. The squads are your distance sensor, and they tend to be honest if you give them permission to be.

There's a second, more subtle, reason to take the elevator down: credibility. An architect who really knows the code earns the squads' respect in a way no title grants. When they propose a decision and show they understand the real state of the system —"I know payments still drags that coupling with orders, that's why I suggest this"—, the squads listen, because their word matches the reality they live daily. When they propose from the penthouse, with a mental model from six months ago, the squads detect it instantly —"that's not how it is anymore"— and, even if they don't say it out loud, discount everything they say. The architect's authority to influence without commanding (which is module 4) rests in good part on this: contact with the code not only improves their estimates, it sustains their credibility. An architect the squads trust technically doesn't need to impose; one detached from the code loses the only currency they had left —being right—.

A note to avoid over-correcting: the answer to "they live too far from the code" is not "let them go back to being a full-time developer". The architect has work in the penthouse no one else does —translating the business, aligning the squads, holding the quality attributes— and giving it up to code full-time also breaks the role. The goal is the elevator: moving between floors, not settling on one. An architect who only codes is a senior engineer with an odd title; one who only makes slides is a consultant with no contact with reality. The craft is the journey between the two.

Common mistakes

Believing being senior means being above the code. What happens: the architect treats programming as a junior task they "graduated from", and fills their week with meetings and documents without opening the repository. Why it happens: many organizational cultures reward moving away from technical work as a status signal —"they don't get their hands dirty anymore"—, confusing height with distance. How to spot it: if the architect hasn't read code or reviewed a PR in weeks, and their descriptions of the system clash with what the squads know ("that's not how it is anymore"), they're above the code, not in command of it. How to fix it: reserve recurring and protected time to take the elevator down —read code, review the architect-level PRs, do a spike— and treat it as a central part of the role, not as a regression. Contact with the code is what keeps decisions real; without it, seniority only enlarges the error.

Estimating from the penthouse and making the machine room pay. What happens: the architect promises the business a date based on how the change "looks" from above, the squad inherits an impossible promise, and when the work takes what it really takes, the squad carries the failure. Why it happens: distance from the code produces systematic optimistic underestimation (the 89% of the example), and since the estimate comes "from the architect", no one questions it. How to spot it: if the architect's estimates are consistently smaller than the real effort, and the squads live putting out the fires of dates they didn't set, the architect estimates from the penthouse. How to fix it: don't estimate technical changes without recent contact with the code —or better, don't estimate alone: ask the estimate from whoever touches the code and use the architect role to validate and communicate it, not to invent it from above—. When the architect does want their own reading, a half-day spike is worth more than a penthouse intuition.

Over-correcting and becoming the one who writes all the critical code. What happens: on hearing "the architect must be close to the code", the architect rushes to personally implement every hard part, and now every technical decision waits for them to write the solution. Why it happens: they confuse "close to the code" with "author of the code", the opposite error to the ivory tower. How to spot it: if the architect authors a huge fraction of the critical commits, or if the squads block waiting for them to implement the hard stuff, they became a technical bottleneck. How to fix it: change the type of contact —read, review the few PRs that matter, do bounded spikes, occasional pairing— instead of the volume. The goal is the up-to-date mental model, not authorship. An architect who writes all the critical code knows the system perfectly and still does harm: they concentrate the knowledge and block the team (exactly the lesson 6 trap).

Exercises

Exercise 1 — How far away are you? For each of these Mercado architects, place their approximate code_distance (0 to 5) and predict whether their estimates will be realistic or unrealistically optimistic: (a) reviews the orders/shipping contract PRs every week and did a spike of the catalog cache last month; (b) hasn't opened the repository in eight months, but is in all the strategy meetings; (c) personally writes half the payments service commits; (d) reads new code when they can and sits with the squads in their design sessions, without writing much themselves.

See solution
  • (a) Distance ~1. Regular and selective contact (reviews the PRs that matter) plus a recent spike: their mental model is fresh. Realistic estimates (error ~17% or less). It's a good use of the elevator: they go down to what matters without blocking.
  • (b) Distance ~5. Eight months without code, living in the penthouse of strategy. Unrealistically optimistic estimates (error ~89%): they decide about a Mercado that no longer exists. It's the pure case of the lesson —brilliant in the meeting, wrong on the number—.
  • (c) Distance ~0 in knowledge, but it's the opposite error. Their mental model is perfect (they write the code), so they'd estimate well; the problem is they became the payments bottleneck —the squad depends on their commits—. "Close to the code" wasn't this: it was keeping the model up to date without being the author of everything. Low distance, but lesson 6 pathology.
  • (d) Distance ~1-2, and it's the ideal. They read, sit with the squads, don't write much: fresh mental model without blocking anyone. It's exactly the elevator well run —close to the code without being a bottleneck—. Realistic estimates.

Exercise 2 — The spike as a cure for optimism. The business asks the architect for a date for async_orders_to_shipping. The architect hasn't touched that code in months and their instinct says "about 3 days". Knowing what the example shows, what should they do before giving the date, and why is that worth more than "estimating better from the desk"?

See solution

They should do a spike: go down to the machine room and build, with their own hands, a small prototype of the change —connect orders to shipping asynchronously on a test branch, just for the happy path—. In half a day of spike they'll run into what isn't visible from the desk: how orders handles shipping's synchronous response today, what happens to in-flight orders, how many places in the code assume the immediate response. That contact turns their optimistic "3 days" into an estimate anchored to reality (which the example suggests is near 21).

Why the spike is worth more than "estimating better from the desk": the penthouse estimate's error isn't one of calculation —it's not that they add badly— it's one of information. Their mental model is out of date, so no amount of "thinking about it more" from the desk will fix it; it can only refine a wrong picture. The spike doesn't improve the calculation; it replaces the imaginary picture with the real one. You cook the dish once and stop guessing how long it takes. It's the direct application of "take the elevator down": facing a big decision with technical uncertainty, the architect doesn't guess from above, they go down and touch. (How to structure that spike as a formal experiment is the sister guide; that you have to go down to do it is this lesson.)

Exercise 3 — Resolving the tension with lesson 6. A colleague tells you: "I don't get it, lesson 3 says the architect should be close to the code and lesson 6 will say they shouldn't be the bottleneck; they seem to contradict each other". Explain why they don't contradict, using the distinction between type and volume of contact with the code.

See solution

They don't contradict because they talk about two different things: lesson 3 is about the type of contact (keeping the mental model up to date) and lesson 6 is about the volume of work that passes through the architect (not being the funnel).

"Close to the code" properly understood is reading and sampling contact: reading the code that matters, reviewing the few architect-level PRs, doing an occasional spike, sitting with the squads. None of that blocks anyone —the squads keep deciding and building their own—; it only keeps the architect's head glued to reality. It's low volume and high informational value.

The lesson 6 bottleneck is another matter: it's when the architect becomes the one who produces or approves the work —writes all the critical code, reviews every PR, decides everything—, and then the squads wait for them and the queue grows. It's high volume and blocking.

The practical distinction: you can be at code_distance 1 (fresh mental model) without being the bottleneck, if your contact is reading and sampling instead of producing and approving everything. In fact, that's exactly the ideal architect —case (d) of exercise 1—: close to the code, far from the funnel. The two opposite errors are living in the penthouse (distance 5, bad information) and writing all the critical code (distance 0, but a bottleneck). The craft is in the middle: go down enough to know, without producing so much that everyone depends on you.

Summary and next step

In this lesson you took apart the second false image of the role: the architect detached from the code who decides from the penthouse about a system that no longer exists. You saw, with the chef who stopped going into the kitchen, that the promises and estimates of the one who doesn't go down become unreal, and with Hohpe's elevator you understood that the architect's job is to move between floors, not settle up top. And you measured it: the estimation error grows with distance from the code —from 0% glued to the repo to 89% on nothing but slides— and it's always systematic optimism, so the penthouse promises and the machine room pays. The quality of the architect's decisions is a function of their distance from the code, not of their title.

Before moving on you should be able to: explain the elevator metaphor and why the architect lives in the journey, not on one floor; distinguish "close to the code" (keeping the mental model fresh through reading and sampling) from "writing all the code" (the bottleneck); and propose a spike as a cure for penthouse optimism when facing an uncertain estimate.

Lesson 4 takes the next step: since the architect is present (lesson 2) and close to the code (lesson 3), what exactly is their product? The answer will surprise you: it's not "the right decision". It's a decision whose error is cheap —reversible— plus the communicated why. We'll execute why, under high uncertainty, making the error cheap beats trying to get it right, and why the architect doesn't sell certainties: they sell options that can be undone.

Resources

  • Gregor Hohpe, The Software Architect Elevator (O'Reilly, 2020) — the source of this lesson's central metaphor. The architect connects the business penthouse with the code's machine room; the one who stays up top loses the contact that makes their decisions real. In English.
  • Gregor Hohpe, "The Architect Elevator" — architectelevator.com. The author's site with essays that expand the book, including why the architect shouldn't "live in the penthouse". In English.
  • Mark Richards and Neal Ford, Fundamentals of Software Architecture, 2nd ed. (O'Reilly, 2020), ch. 2 — on keeping technical depth ("technical breadth" and contact with the code) as part of the role, not as a luxury. In English.
  • Martin Fowler, "Who Needs an Architect?" (IEEE Software, 2003) — martinfowler.com/ieeeSoftware/whoNeedsArchitect.pdf. Fowler insists that the valuable architect is immersed in the project and programs with the team, not directing it from outside. In English.
← PreviousThe ivory tower mythNext →Reversible over right