Module 1: What an Architect Really Does

Module introduction: what an architect actually does

Why this module exists here

Ask ten people what a software architect does and nine will describe the same person: someone who locks themselves away for a few weeks, draws the system's definitive diagram —boxes, arrows, layers, a cloud that says "Kafka"—, presents it in an important meeting, and then goes back to their tower to design the next one. The diagram is pretty. The image is prestigious. And it is, almost entirely, false. Not false because architects don't draw —they do—, but false in what it believes the work is. The architect's work isn't the diagram; the diagram is a byproduct. This module dismantles that image and puts in its place the one that holds up the whole guide: the real architect doesn't produce diagrams, they produce the conditions for a system and an organization to evolve well.

This whole guide teaches the human and organizational craft of being an architect: how the structure of teams shapes that of the system (Conway's law, module 2), how to communicate architecture so different audiences understand it (C4, module 3), how to lead without formal authority (module 4), how to translate business goals into quality attributes (module 5), how to plan for change (module 6), and how to document in a way that survives (module 7). All of that rests on an idea of the role. If your idea of the role is "the one who draws the perfect diagram", the rest of the guide has nothing to lean on. That's why this module comes first: it installs what the role is —and what it isn't— before teaching how it's practiced.

Let's go to the case that accompanies us through the whole guide. Mercado is a marketplace, and here it's not just the system: it's the system and its organization. Five squads split the work:

catalog — the product catalog, search, the listings.
orders — the cart, checkout, the order lifecycle.
payments — charging, payment providers, reconciliation.
shipping — shipment, labels, tracking.
platform — the cross-cutting stuff: authentication, observability, CI/CD, shared infrastructure.

There are also business stakeholders —a VP of product who asks for features, finance that watches the costs, operations that suffers when checkout goes down— and, in the middle of it all, an architect who must align five squads with business goals without becoming the funnel every decision passes through. That's the real setting of the craft, and it's where this module works. Notice what the setting is not: it's not an architect alone before a blank canvas. It's an architect in front of people who are already building, deciding, and sometimes clashing.

Connection with the module. This is the map lesson. It doesn't go deep into any tool; it installs the thesis (the architect produces reversible decisions, a communicated why, and enabled teams, not diagrams), the vocabulary (architect-level vs. local decision, ivory tower, the elevator, guardrails, bottleneck, BDUF, last responsible moment), and the map of how each lesson dismantles a false image and assembles a real one. Lesson 2 takes apart the ivory tower. Lesson 3 explains why the architect stays close to the code (the elevator). Lesson 4 defines their real product: reversible decisions plus the why. Lesson 5 casts them as a gardener who enables, not a dictator. Lesson 6 measures the central danger: the bottleneck. Lesson 7 sets BDUF against the last responsible moment. And lesson 8 puts you to diagnosing and redesigning Mercado's architect role, executed. Watch the frontier, which is deliberate: the method of deciding —how to compare options with a matrix, the mechanics of the ADR, the fitness function, reversibility as a technique— is taught by the sister guide architecture-decisions-and-tradeoffs; Conway's law is module 2; C4 is module 3; leadership without authority in depth is module 4. Here we only install what the role is and dismantle its myths.

And a promise kept throughout the module: even though the subject is human, what's quantifiable is executed, not asserted. Every simulation runs with Python 3.14 and the standard library only, with fixed data, so the output you see in each "What to expect" block is the literal output of running the code. You can copy it and reproduce it identically.

An analogy: the building architect who doesn't disappear after the blueprint

Think of a building architect, the real one, the one who builds houses. There are two ways to imagine their work, and only one is real.

The false image. The architect sits in their studio, draws the perfect blueprints of the building —every wall, every window, every pipe in its place—, rolls them up, hands them to the site foreman, and leaves. From there on, "it's the builders' problem". If something fails, it was because they didn't follow the blueprint. In this image, the architect is a document producer: their work begins and ends on paper.

The real image. A good building architect delivers the blueprints, yes, but that's the start of their work, not the end. They visit the site. They walk the ground and discover the soil is softer than the survey said, so they adjust the foundation. They talk to the builders and learn that the wall they drew for three days takes two weeks because of how the material arrives, so they rethink the sequence. They stand in front of a window opening, see it faces an ugly wall of the neighbor, and reorient it right there. When the client changes their mind mid-build —"I want the kitchen open"—, they don't say "the blueprint is already signed"; they sit down and redesign that part. The blueprint wasn't a prophecy reality had to obey; it was a hypothesis that reality kept correcting, and the architect was there to correct it.

Here's the point: the real architect doesn't disappear after the blueprint. Their value isn't in the perfect drawing they delivered on day one —that drawing, against reality, was always partly wrong—. Their value is in staying present: going down to the site, talking to whoever builds, adjusting when the ground or the client forces it, and holding the building's coherence across months of small decisions no one wrote down in the original blueprint. The software architect is the same. The day-one diagram is a hypothesis. The work is everything that comes after: going down to the code (the site), talking to the squads (the builders), adjusting when the business changes (the client), and doing it without becoming the person every hammer blow has to pass through. This module trains that presence, and takes apart, one by one, the four ways of believing the work was just the blueprint.

Worked example: separating architect-level decisions from the squad's

If the architect doesn't draw diagrams all day, what do they get their hands into? The answer starts with one that almost nobody does well: choosing which decisions to get into. An architect who wants to weigh in on everything drowns and drowns the team; one who weighs in on nothing adds nothing. The craft is in distinguishing the few decisions that are truly architect-level from the many that belong to the squad that lives with them. And that distinction isn't made "by eye": it can be measured.

We score each of Mercado's open decisions on three axes, from 1 to 5:

cross_team — how many squads the decision couples (5 = all of them). A decision that only touches one squad is that squad's business; one that forces several to coordinate is, by definition, the architect's.
reverse_cost — how hard it is to reverse (5 = almost irreversible).
blast_radius — how much of the system it affects (5 = everything).

The rule is simple: if the sum of the three is 9 or more, the decision crosses boundaries, is expensive, and has a wide radius —it's architect-level, even though the architect decides it with the squad, not above it—. If it doesn't reach 9, the squad owns it, and the architect stays out:

# Mercado's open decisions across 5 squads (catalog, orders, payments,
# shipping, platform). Each scored 1-5 on three axes:
#   cross_team    = how many squads the decision couples  (5 = all)
#   reverse_cost  = how hard it is to reverse             (5 = almost irreversible)
#   blast_radius  = how much of the system it affects      (5 = everything)
# Rule: if sum >= 9, it's an ARCHITECT-level decision (crosses squads,
# expensive, wide); if not, the squad OWNS it, and the architect stays out.
DECISIONS = [
    # (id, owning_squad, cross_team, reverse_cost, blast_radius)
    ("extract_catalog_to_service",   "catalog",  5, 5, 4),
    ("orders_to_shipping_contract",  "orders",   4, 4, 4),
    ("shared_auth_token_change",     "platform", 5, 4, 5),
    ("add_second_payments_provider", "payments", 3, 4, 3),
    ("catalog_search_page_size",     "catalog",  1, 1, 1),
    ("orders_retry_count",           "orders",   1, 1, 2),
    ("shipping_label_font",          "shipping", 1, 1, 1),
    ("checkout_button_color",        "catalog",  1, 1, 1),
]


def architect_level(cross, reverse, blast):
    # It's architect-level when it crosses squads AND is expensive AND wide.
    return cross + reverse + blast >= 9


print(f"{'decision':<32}{'squad':<10}{'x-team':>7}{'rev':>5}{'blast':>7}  owner")
print("-" * 74)
architect_count = 0
for decision_id, squad, cross, reverse, blast in DECISIONS:
    if architect_level(cross, reverse, blast):
        owner = "ARCHITECT (+ squad)"
        architect_count += 1
    else:
        owner = f"{squad} squad decides"
    print(f"{decision_id:<32}{squad:<10}{cross:>7}{reverse:>5}{blast:>7}  {owner}")

print()
total = len(DECISIONS)
print(f"Of {total} decisions on the table, only {architect_count} are architect-level.")
print(f"The other {total - architect_count} are decided by their squad. An architect who wants")
print("to touch all 8 becomes the bottleneck of all of Mercado.")

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

decision                        squad      x-team  rev  blast  owner
--------------------------------------------------------------------------
extract_catalog_to_service      catalog         5    5      4  ARCHITECT (+ squad)
orders_to_shipping_contract     orders          4    4      4  ARCHITECT (+ squad)
shared_auth_token_change        platform        5    4      5  ARCHITECT (+ squad)
add_second_payments_provider    payments        3    4      3  ARCHITECT (+ squad)
catalog_search_page_size        catalog         1    1      1  catalog squad decides
orders_retry_count              orders          1    1      2  orders squad decides
shipping_label_font             shipping        1    1      1  shipping squad decides
checkout_button_color           catalog         1    1      1  catalog squad decides

Of 8 decisions on the table, only 4 are architect-level.
The other 4 are decided by their squad. An architect who wants
to touch all 8 becomes the bottleneck of all of Mercado.

Read the table calmly, because the module's central idea is in that split.

At the top are the four architect-level decisions. Notice what they have in common: they all score high on cross_team. Extracting the catalog to a service (extract_catalog_to_service) forces catalog, orders, and everyone who reads the catalog to agree on a new contract. The contract between orders and shipping (orders_to_shipping_contract) is, literally, the boundary between two squads. Changing the shared authentication token (shared_auth_token_change) touches all five. Adding a second payments provider (add_second_payments_provider) redefines how payments talks to the world. None of these can a single squad decide alone because none fits inside a single squad: they all cross boundaries. And that's the operational definition of an architect-level decision —not "the one that sounds important", but the one that couples teams that would otherwise decide separately—.

At the bottom are the four local ones. The page size of catalog search, the retry count of orders, the shipping label's font, the checkout button's color: each one lives entirely within a squad, reverts in one commit, and affects no one else. An architect who calls a meeting to decide a button's color isn't being careful; they're stealing a decision from the catalog squad that is theirs, and putting themselves in the path of a trivial change on the way. Multiply that by the dozens of local decisions the five squads make each week and you have the exact recipe for the bottleneck lesson 6 will measure.

The takeaway reading: of eight decisions, the architect touches four —half—, and even that is a toy case with only eight. In a real Mercado, with dozens of decisions a week, the proportion that reaches the architect should be much smaller. The first act of the craft isn't to decide well; it's to decide which decisions to get into, and to have the discipline to let go of all the rest. An architect who doesn't let go becomes the funnel of their own organization.

The four false images and the four real ones

That example touched, without developing them, the module's ideas. Each lesson takes a false image of the role and replaces it with the real one. It's worth seeing them together, because they're the backbone of the seven lessons that follow.

1. The ivory tower (lesson 2). False: the architect draws the perfect diagram and leaves. Real: the day-one diagram is a hypothesis reality corrects; the work is being present to correct it. Lesson 2 measures how much of Mercado's "perfect diagram" survived the build.

2. Detached from the code (lesson 3). False: the architect is too senior to touch code; they live in meetings and slides. Real: the architect goes up to the business and down to the machine room —Hohpe's elevator—; without closeness to the code, their decisions rest on an old mental model and their estimates are wrong. Lesson 3 measures how the error grows with distance from the code.

3. The dictator and the bottleneck (lessons 4, 5, and 6). False: the architect decides everything and is always right; every decision passes through them. Real: their product is a reversible decision (making a mistake cheap) plus the communicated why (lesson 4); they enable the team like a gardener who sets guardrails, not like a dictator (lesson 5); and they know that wanting to decide everything turns them into the bottleneck whose queue grows without end (lesson 6).

4. Big Design Up Front (lesson 7). False: a good architect designs everything up front, complete, before writing a line. Real: they decide each thing at the last responsible moment —when their information matures—, neither before (BDUF, and you pay rework) nor after (paralysis, and you pay the default). Lesson 7 measures the overcost of deciding blind.

Keep this map; it's the module's route:

False image                      Lesson    What the real architect does
───────────────────────────────  ────────  ──────────────────────────────────
The ivory tower                  L2        be present; the blueprint is a hypothesis
Detached from the code           L3        the elevator: go down to the machine room
Decides all, is always right     L4        sells reversible decisions, not certainties
The dictator                     L5        gardener: guardrails and autonomy
The bottleneck                   L6        design NOT to be the funnel
Big Design Up Front              L7        decide at the last responsible moment
───────────────────────────────  ────────  ──────────────────────────────────
Diagnose and redesign the role   L8        the mini-project, executed

The map: where this module sits in the guide and the ecosystem

This module is the entry point. Here's how it connects with the rest of the guide:

flowchart TD
    M1["M1 · What an architect actually does<br/>(dismantle the myths of the role)"]
    M2["M2 · Conway's law"]
    M3["M3 · Communicating architecture (C4)"]
    M4["M4 · Technical leadership without authority"]
    M5["M5 · Stakeholders and quality attributes"]
    M6["M6 · Designing for change"]
    M7["M7 · Documentation that survives"]
    M8["M8 · Project: be Mercado's architect<br/>for a change"]
    M1 --> M2 --> M3 --> M4 --> M5 --> M6 --> M7 --> M8

Read it like this: here you learn what the role is and dismantle its myths; in M2 you see how the structure of teams shapes that of the system (Conway); in M3 you communicate architecture with C4; in M4 you lead without formal authority; in M5 you translate business goals into quality attributes; in M6 you plan for change; in M7 you document so it survives; and in M8 you make the whole journey as Mercado's architect facing a real change.

And the frontier with the ecosystem's sister guide, which must be respected: architecture-decisions-and-tradeoffs teaches the method of deciding —comparing options with a weighted matrix, the mechanics of the ADR, writing a fitness function, classifying a decision by its reversibility—. This guide teaches the craft around it: how the human who makes those decisions relates to the organization, communicates, and leads so they get executed. They're complementary: the decision vs. the human who makes it happen. When in lesson 4 we talk about "reversible" decisions, we won't re-teach the mechanics of reversibility (that's the other guide); we'll teach why making expensive decisions reversible is part of what the role means.

Common mistakes

These three mistakes are the three pathologies of the role the whole module fights. They appear here in summary form; each lesson opens one in depth.

Believing the diagram is the deliverable (the ivory tower). What happens: the architect invests weeks in the perfect diagram, presents it, and considers their work done —"there's the architecture, execute it"—. Why it happens: the diagram is visible, prestigious, and feels like "producing something", while the real work —being present, adjusting, enabling— is diffuse and doesn't show on a slide. How to spot it: if the architect appears at a project's start and disappears during construction, or if the diagram they delivered three months ago no longer resembles what's being built and no one is surprised, you're facing an ivory tower. How to fix it: treat the diagram as a hypothesis reality will correct, and measure your value by your presence during construction, not by the quality of the initial blueprint. Lesson 2 quantifies it: 70% of Mercado's perfect diagram was redone during the build.

Detaching from the code and deciding on an old mental model. What happens: the architect goes a year without opening the repository, decides based on how they believe the system is, and their decisions and estimates fail because the system is no longer the one they remember. Why it happens: "senior" is confused with "above the code", as if touching code were junior stuff. How to spot it: if the architect estimates a change takes three days and it takes the squad three weeks, and this happens often, their mental model is out of date. How to fix it: take the elevator down regularly —read the code, review PRs, do a spike now and then— to keep the mental model glued to reality. Lesson 3 measures how the estimation error grows with distance from the code.

Becoming the bottleneck by wanting to decide everything (the dictator). What happens: every decision, big or small, has to pass through the architect for approval, so the squads wait, a queue forms, and the architect works nights unable to keep up. Why it happens: it comes from a good but miscalibrated place —"I want it to turn out well"—, but it confuses "the important decisions turning out well" with "me making all the decisions". How to spot it: if the squads often say "we're waiting for the architect to review this", or if the architect is the busiest and most blocking resource on the team, it's a bottleneck. How to fix it: separate the few architect-level decisions from the many local ones (like this lesson's example), and enable the squads with guardrails so they decide their own alone. Lessons 5 and 6 develop and measure it: the bottleneck accumulates 1430 decision-weeks of waiting; the distributed model, zero.

Exercises

Exercise 1 — Architect or squad? For each of these Mercado decisions, say whether you'd treat it as architect-level (crosses squads, expensive, wide) or local (its squad decides), and justify with at least one of the three axes (cross_team, reverse_cost, blast_radius): (a) changing the text of the order confirmation email; (b) defining the format of the events orders publishes that shipping, payments, and analytics consume; (c) choosing the charting library for catalog's internal dashboard; (d) migrating all squads from in-memory sessions to signed tokens.

See solution

(a) Email text → local. It lives within the squad that sends notifications, reverts by editing a template, and couples no one. cross_team extremely low. Its squad decides.
(b) Format of orders's events → architect-level, one of the clearest. It's a contract consumed by shipping, payments, and analytics: cross_team maxed out. Changing it badly breaks three squads at once, and once everyone depends on the format, reverting it is expensive. It's exactly the kind of decision only the architect can hold, because they're the only person with the view of the three squads at once. (How to design that event is a topic for the technical guides; that it's an architect-level decision is what matters here.)
(c) Charting library for catalog's internal dashboard → local. Only catalog uses it, it changes without touching anyone else, blast_radius minimal. Its squad decides. An architect who weighs in on this is stealing a decision from the squad.
(d) In-memory sessions → signed tokens → architect-level. It touches how all five squads verify identity: cross_team and blast_radius high, and reverting it once the tokens are issued is expensive. It's the architect's —with the squads—, not a single one's.

Exercise 2 — The blueprint isn't the work. An architect new to Mercado presents, in their second week, a very complete diagram of how the system "should" look in two years, with all the services already split and all the contracts defined. They present it and expect the squads to execute it. Name two reasons, using the building-architect analogy, why that diagram —however good it is— is not yet "doing architecture".

See solution

The blueprint is a hypothesis, not a prophecy. The building architect who draws the perfect house on day one hasn't yet set foot on the ground: they don't know the soil is soft, that the material is slow, that the client will want the open kitchen. Their diagram of "how it should look in two years" is, guaranteed, partly wrong —because it was made before reality corrected it—. Presenting it as a plan to execute confuses the hypothesis with the work. Lesson 2 measures it: 70% of a perfect diagram is redone during the build.
The work is presence, not delivery. Even if the diagram were perfect, delivering it and expecting them to "execute it" is exactly the ivory tower: the building architect's value isn't in rolling up the blueprints and leaving, but in visiting the site, talking to the builders (the squads), and adjusting over months. A diagram without presence isn't architecture; it's a drawing. And there's an extra problem: imposing a two-year plan the squads didn't help build is dictating, not enabling (lesson 5) —they'll hardly execute it as their own—.

Exercise 3 — The first act of the craft. An architect tells you: "to do my job well I need to review and approve every PR from the five squads, that way I make sure everything is right". Explain why that stance, though it sounds responsible, is the opposite error to the one they should make, and what they should do instead.

See solution

It sounds responsible —"I make sure everything is right"— but it confuses "the important decisions turning out well" with "me reviewing everything". Reviewing every PR from the five squads turns the architect into the bottleneck of the whole organization: the squads wait for their review, the queue grows, and the architect drowns reviewing trivial local decisions (a button's color, a variable name) that aren't at their level. The cost of that waiting queue is measurable, and lesson 6 measures it: when everything passes through one person, the accumulated wait explodes.

What they should do is the first act of the craft this lesson's example taught: separate the few architect-level decisions (the ones that cross squads, are expensive, wide) from the many local ones, get into only the first —with the squad, not above it—, and enable the squads to decide their own alone, giving them clear guardrails instead of case-by-case approval (lesson 5). Their job isn't to review everything; it's to design the system so most decisions don't need to pass through them. An architect who reviews every PR isn't more responsible; they're more blocking.

Summary and next step

In this lesson you dismantled the image almost everyone has of the role —the genius who draws the perfect diagram and leaves— and replaced it with the real one: the architect produces reversible decisions, a communicated why, and enabled teams, not diagrams. You saw, with the building architect, that the day-one blueprint is a hypothesis and that the work is the presence that corrects it. And you measured it: you classified Mercado's open decisions and saw that only half —the ones that cross squads— are architect-level, while the local ones belong to their squads; an architect who wants to touch them all becomes the bottleneck of their own organization.

Before moving on you should be able to: explain why the diagram is a byproduct and not the work; name the four false images of the role and the four real ones; distinguish an architect-level decision from a local one with a Mercado example; and argue why wanting to decide everything is a mistake, not a virtue.

Lesson 2 takes the first false image and takes it apart in depth: the ivory tower. You'll see why the perfect diagram doesn't survive contact with reality —not because it's badly drawn, but because it was drawn before reality spoke— and execute how much of Mercado's upfront design had to be redone during the build. With numbers, so that "the blueprint isn't the work" stops being a slogan and becomes a measurement.

Resources

Martin Fowler, "Who Needs an Architect?" (IEEE Software, 2003) — martinfowler.com/ieeeSoftware/whoNeedsArchitect.pdf. The founding essay of this module. Fowler distinguishes the "Architectus Reloadus" (the one who decides everything and everyone consults —the bottleneck—) from the "Architectus Oryzus" (the one who mentors, converses, and enables the team). It's exactly the contrast the whole module works. Short and essential. In English.
Mark Richards and Neal Ford, Fundamentals of Software Architecture, 2nd ed. (O'Reilly, 2020), ch. 1–2 "Introduction / Architectural Thinking" — the guide's central reference on what the role is and isn't. It defines the architect's expectations and why "thinking like an architect" isn't drawing better. In English.
Gregor Hohpe, The Software Architect Elevator (O'Reilly, 2020) — the book that gives the elevator metaphor (going up to the business penthouse, down to the code's machine room) that lesson 3 develops. The introduction already makes the thesis clear: the architect connects floors, doesn't live on one. In English.
Matthew Skelton and Manuel Pais, Team Topologies (IT Revolution, 2019) — the framework of team types (stream-aligned, platform, enabling, complicated-subsystem) that underpins the idea of "enabling" and guardrails, and that lesson 5 and module 2 use in depth. In English.

Next →The ivory tower myth