Module 8: Capstone Project — Be Mercado's Architect Through a Change

5. Produce the C4 and the ADR

Next →

Overview

This is step 4 of the deliverable, and it's where the decision becomes communicable. In lesson 4 you decided the structure —create the seller_platform team, expose a Seller API, turn the platform into a service, with two seams by contract—. But a decision that lives only in the architect's head builds nothing: it has to be communicated, and to two very different audiences —the VP who approves the budget and the dev who's going to build—. By the end of this lesson you'll have two deliverable artifacts: the C4 of the change (the diagram that shows the what at the right level for each audience) and the complete ADR-021 (the record that packages the why for whoever comes after). The diagram and the ADR are the two halves of communicating an architecture: the diagram is the photo, the ADR is the story of why the photo looks like this.

This matters because in a big change the communication decides whether the decision survives time and people. The C4 avoids the two badly served audiences: the VP drowning in a technical diagram they don't understand, and the dev lost in a business diagram that doesn't tell them where each thing lives. And the ADR solves the most expensive problem of all —the knowledge that's lost when whoever decided leaves—: two years from now, the dev who inherits the sellers surface and thinks "this would be simpler without the gateway" will open the ADR-021 and find why the gateway exists, what was sacrificed on purpose (the extra latency, the two seams), and so won't undo a good decision through ignorance. In the capstone, moreover, the ADR is the piece that connects all the previous steps: its context cites the governing attribute (step 2), its decision describes the structure (step 3), and its consequences name the irreducible seams and the trade-off that governs the change —the ADR is where the thread becomes text—.

Connection with the module: this lesson does step 4 of the thread and contributes the M3 piece to the capstone. It receives its input from step 3 (the structural decision to communicate) and from step 2 (the governing attribute, which the ADR cites as justification). Its output —the C4 and the ADR— feeds step 5 (the rollout): the diagram and the ADR are the tools with which the architect influences the squads to adopt the contract of the change, and they're part of the documentation that step 6 will version. The frontier with the sister guide stays firm, just as in module 3: the mechanics of the ADR (its structure, when to write it, how it's superseded) were taught in architecture-decisions-and-tradeoffs; here the ADR is used as a communication piece, its mechanics aren't re-explained. The novelty isn't the ADR format, it's its role: how a well-written ADR speaks to a future reader.

Two maps and a note from the previous owner

Think of a city you visit for the first time. You take two maps of the same place. One is the tourist map: the city as a blob with its points of interest and how they relate in broad strokes —with that you understand what the city is without drowning in detail—. The other is the subway map: the lines, the stations, the transfers —the pieces you actually move by—. No one confuses one for the other: the tourist map would be useless for knowing which station to change lines at, and the subway map would be overwhelming for someone who just wants to know what the city has that's interesting. The Context of the C4 is the tourist map (for the VP); the Container is the subway map (for the dev). Same city —Mercado after the change—, two maps, two audiences.

But there's something no map tells you: why the city is built this way. For that, imagine you move into an old house and find, taped inside the fuse box, a note from the previous owner: "I walled up the garage door because it opened onto a plot that floods; the pipe goes around because there's a beam underneath that can't be drilled". Suddenly, what looked like incompetence turns out to be informed decisions against constraints you couldn't see. That's an ADR. The diagram shows that the sellers surface is behind a gateway; it doesn't say why. The ADR is the note today's architect tapes to the fuse box for the dev two years from now, so they don't unwall the garage and flood it. The diagram is the map; the ADR is the note. In step 4 you produce both.

Worked example: the C4 of the change

Let's start with the diagram, in two levels. The Context answers: what does Mercado do after the change, who uses it, and what does it depend on? The novelty of the change jumps out —an external seller who now integrates via API, with their own system (the Seller Backend)—.

C4Context
    title Mercado after the change - System Context (level 1, the VP's map)
    Person(customer, "Customer", "Searches for and buys products")
    Person(seller, "Seller (external)", "Publishes and sells via the Seller API")

    System(mercado, "Mercado", "Marketplace: now open to external sellers via API")

    System_Ext(sellerbe, "Seller Backend", "The third party's ERP/e-commerce that integrates")
    System_Ext(payments, "Payment Gateway", "Processes payments and payouts")
    System_Ext(carrier, "Carrier API", "Generates labels and tracks shipments")

    Rel(customer, mercado, "Searches, buys, tracks orders")
    Rel(seller, mercado, "Publishes products, manages inventory")
    Rel(sellerbe, mercado, "Syncs catalog and receives payouts", "HTTPS/API")
    Rel(mercado, payments, "Charges and pays sellers", "HTTPS/API")
    Rel(mercado, carrier, "Requests shipments", "HTTPS/API")

Read it as the VP would: customers buy; external sellers publish via the API; the seller's system (their ERP) syncs with Mercado; and Mercado charges and pays via a gateway and ships via a carrier. Six boxes, zero jargon, and the story of the change in thirty seconds —the VP sees there's now a new actor (the third party) integrating via API, which is exactly what they approved—. The internal gateway doesn't appear, nor PostgreSQL, nor the seller_platform service, and that's fine: the VP didn't come for that.

Now the Container: we zoom inside Mercado. It answers: what deployable pieces does it consist of and how do they communicate? Here appears what the change added on the inside —the Seller API gateway and the seller_platform service—.

C4Container
    title Mercado after the change - Containers (level 2, the dev's map)
    Person(customer, "Customer", "Buys")
    Person(seller, "Seller (external)", "Sells via API")

    System_Boundary(mercado, "Mercado") {
        Container(web, "Web App", "React", "Storefront in the browser")
        Container(mobile, "Mobile App", "React Native", "Shopping app")
        Container(storefront, "Storefront API", "FastAPI", "Catalog, orders, checkout")
        Container(gateway, "Seller API Gateway", "API Gateway", "Third-party auth, rate limiting, quotas")
        Container(sellerplat, "seller_platform", "Service", "Onboarding, listing ingestion, payouts")
        ContainerDb(db, "Database", "PostgreSQL", "Products, orders, users")
        Container(search, "Search Index", "Elasticsearch", "Catalog search")
    }

    System_Ext(sellerbe, "Seller Backend", "Third party's ERP")
    System_Ext(payments, "Payment Gateway", "Stripe")
    System_Ext(carrier, "Carrier API", "Ships")

    Rel(customer, web, "Uses", "HTTPS")
    Rel(seller, sellerbe, "Operates their store")
    Rel(sellerbe, gateway, "Integrates", "JSON/HTTPS")
    Rel(gateway, sellerplat, "Routes authenticated requests", "JSON/HTTPS")
    Rel(sellerplat, storefront, "Publishes listings via contract", "JSON/HTTPS")
    Rel(sellerplat, payments, "Orders payouts", "HTTPS/API")
    Rel(web, storefront, "Calls", "JSON/HTTPS")
    Rel(storefront, db, "Reads and writes", "SQL")
    Rel(storefront, search, "Queries and indexes", "HTTPS")
    Rel(storefront, payments, "Charges", "HTTPS/API")

Read it as the new dev would: the external seller's system integrates against a Seller API Gateway (which does third-party auth, rate limiting, and quotas —the door's control—), which routes to the seller_platform service (onboarding, listing ingestion, payouts); seller_platform publishes the listings into the catalog by contract through the Storefront API, and orders the payouts to the external payment gateway. The rest of the system —web, mobile, the Storefront API, PostgreSQL, Elasticsearch— stays as it was. In a minute, the dev knows what pieces the change added, with what technology, and how an external seller's request flows from their ERP to the catalog. Notice that the two genuine seams of lesson 4 appear here as explicit arrows: sellerplat → storefront (publish listings) and sellerplat → payments (payouts). The diagram makes them visible as contracts, not as couplings.

How much detail each zoom carries, measured

The two maps are of the same system but carry different amounts of detail. Let's count it, because "less detail" isn't "less honest": it's the right detail for each audience's question. This same block also generates the ADR —the why— from structured data.

# Capstone step 4: communicate the decision. The C4 (in mermaid, separate) shows the WHAT;
# the ADR shows the WHY, packaged to travel through time. Here we GENERATE the
# ADR of the flagship decision of the change from structured data, and we count
# how much detail each level of the C4 carries for each audience.

adr = {
    "id": "ADR-021",
    "title": "Expose external sellers with a dedicated Seller API and a seller_platform team",
    "status": "Accepted",
    "date": "2026-07-20",
    "deciders": ["architect", "VP of product", "leads of catalog / payments / platform"],
    "context": (
        "We open Mercado to external sellers via API and expect to grow 10x. The "
        "attribute that weighs most is scalability (score 38), followed by security (30) "
        "because third parties enter. Today the sellers surface has no owner: catalog, "
        "orders and payments would each grow a co-owned appendage (measured friction "
        "of 21 pairs of coordination). It's an architecturally significant decision: "
        "it shapes the structure, it's expensive to reverse and it's high-risk (exposes third parties)."
    ),
    "decision": (
        "Create a public Seller API behind an API gateway (third-party auth, rate "
        "limiting, quotas), and a stream-aligned team 'seller_platform' that owns the "
        "complete surface (seller_api, seller_onboarding, listing_ingestion, "
        "payout_processing). catalog, payments, notifications and auth are consumed as "
        "platform services via a stable contract."
    ),
    "consequences_pos": [
        "A single team owns the surface: it scales and evolves without coordinating with four squads (serves grow_10x).",
        "The public contract isolates third parties from the internal model: safer and easier to change on the inside.",
        "The system's coordination friction drops from 21 to 7 pairs (-67%).",
    ],
    "consequences_neg": [
        "A new team to hire and set up: the improvement is the destination, not the first day.",
        "The gateway adds a hop on the critical path: latency and failures must be watched (clashes with instant_checkout).",
        "Two genuine seams remain (importing listings to the catalog; paying the sellers via payments) that require stable contracts.",
    ],
}


def render_adr(a):
    out = []
    out.append(f"# {a['id']}: {a['title']}")
    out.append("")
    out.append(f"**Status:** {a['status']}  |  **Date:** {a['date']}  |  "
               f"**Deciders:** {', '.join(a['deciders'])}")
    out.append("")
    out.append("## Context")
    out.append(a["context"])
    out.append("")
    out.append("## Decision")
    out.append(a["decision"])
    out.append("")
    out.append("## Consequences")
    out.append("In favor:")
    for c in a["consequences_pos"]:
        out.append(f"- {c}")
    out.append("Against (the price we accept):")
    for c in a["consequences_neg"]:
        out.append(f"- {c}")
    return "\n".join(out)


print(render_adr(adr))
print()
print("-" * 70)

# How much detail each level of the C4 carries for each audience of the change.
context_elements = [
    ("person", "Customer"), ("person", "Seller (external)"),
    ("software_system", "Mercado"),
    ("external_system", "Seller Backend"), ("external_system", "Payment Gateway"),
    ("external_system", "Carrier API"),
]
container_elements = [
    ("person", "Customer"), ("person", "Seller (external)"),
    ("container", "Web App"), ("container", "Mobile App"), ("container", "Storefront API"),
    ("container", "Seller API Gateway"), ("container", "seller_platform Services"),
    ("container_db", "Database"), ("container", "Search Index"),
    ("external_system", "Seller Backend"), ("external_system", "Payment Gateway"),
    ("external_system", "Carrier API"),
]


def summarize(name, elements):
    kinds = {}
    for kind, _ in elements:
        kinds[kind] = kinds.get(kind, 0) + 1
    detail = ", ".join(f"{v} {k}" for k, v in kinds.items())
    print(f"{name:<11} {len(elements):>2} elements  ({detail})")


print("The SAME system after the change, two zooms:")
summarize("Context", context_elements)
summarize("Container", container_elements)
print()
print("The VP reads the Context: sees there's now an external Seller integrating via API.")
print("The dev reads the Container: sees the new gateway and the seller_platform service.")
print("The ADR tells both WHY that gateway exists. The diagram doesn't say it.")

What to expect. Running it:

# ADR-021: Expose external sellers with a dedicated Seller API and a seller_platform team

**Status:** Accepted  |  **Date:** 2026-07-20  |  **Deciders:** architect, VP of product, leads of catalog / payments / platform

## Context
We open Mercado to external sellers via API and expect to grow 10x. The attribute that weighs most is scalability (score 38), followed by security (30) because third parties enter. Today the sellers surface has no owner: catalog, orders and payments would each grow a co-owned appendage (measured friction of 21 pairs of coordination). It's an architecturally significant decision: it shapes the structure, it's expensive to reverse and it's high-risk (exposes third parties).

## Decision
Create a public Seller API behind an API gateway (third-party auth, rate limiting, quotas), and a stream-aligned team 'seller_platform' that owns the complete surface (seller_api, seller_onboarding, listing_ingestion, payout_processing). catalog, payments, notifications and auth are consumed as platform services via a stable contract.

## Consequences
In favor:
- A single team owns the surface: it scales and evolves without coordinating with four squads (serves grow_10x).
- The public contract isolates third parties from the internal model: safer and easier to change on the inside.
- The system's coordination friction drops from 21 to 7 pairs (-67%).
Against (the price we accept):
- A new team to hire and set up: the improvement is the destination, not the first day.
- The gateway adds a hop on the critical path: latency and failures must be watched (clashes with instant_checkout).
- Two genuine seams remain (importing listings to the catalog; paying the sellers via payments) that require stable contracts.

----------------------------------------------------------------------
The SAME system after the change, two zooms:
Context      6 elements  (2 person, 1 software_system, 3 external_system)
Container   12 elements  (2 person, 6 container, 1 container_db, 3 external_system)

The VP reads the Context: sees there's now an external Seller integrating via API.
The dev reads the Container: sees the new gateway and the seller_platform service.
The ADR tells both WHY that gateway exists. The diagram doesn't say it.

First the count, which confirms the C4's discipline. The Context carries 6 elements and the Container 12 —double—: the zoom from level 1 to 2 opens the single "Mercado" box into its deployable pieces without touching the world around it (the 2 people and the 3 external systems are preserved identically). The VP sees 6 boxes and understands the change; the dev sees 12 and knows where each thing lives. Neither of them sees the code —level 4—, because neither needs it yet. The lesson of the count: communicating well isn't showing everything, it's showing the right detail for each person's question.

Now the ADR, which is where the capstone's thread becomes text. Read it with the eyes of the future dev who inherits the surface and thinks "why this extra gateway? it'd be simpler without it". The Context makes them feel the tension and —crucially— cites step 2 and step 3: it says scalability (38) is the governing attribute and security (30) the second (why they matter), and that without an owner the surface would have 21 pairs of friction (why the team was created). The dev understands the decision wasn't a whim: it was the answer to the attribute the business prioritized. The Decision describes exactly the structure of lesson 4. And the Consequences are the most honest and most useful part: they don't only list the benefits (an owning team, the contract that isolates, the friction 21→7), but the conscious price —the new team that has to be set up, the extra gateway latency that clashes with instant_checkout, and the two irreducible seams—. When the future dev notices that latency, the ADR will tell them "yes, we knew, it was the price of the separation", and they won't lose a week investigating a "problem" that was a decision. The diagram showed them the photo; the ADR told them the story —including what hurt—.

Notice a detail that lesson 7 is going to exploit: since the ADR came from structured data and fits on one screen, it's a small text file that can live in the repository, versioned alongside the code, changing when the decision changes. Just like the C4 in mermaid, which is text and not an image that rots. That property —diagrams and decisions as versionable text— is the basis of the documentation that survives of step 6.

Deep dive: why the diagram and the ADR are inseparable in the capstone

It's worth fixing the division of labor between the two pieces, because together is how they truly communicate an architecture —and in the capstone that union is especially important—.

Communicates the...Ages...Answers...
Diagram (C4)what — the shape of the system after the changewhen the structure changeswhoever needs to orient themselves in the current system
ADRwhy — the reasoning behind italmost never (the decision and its context are historical)whoever needs to understand why the system is this way

There's a useful asymmetry. The diagram describes the present, so it ages every time the system changes —it has to be maintained—. The ADR describes a historical moment —"in July 2026, given these conditions, we decided this"—, and that moment never changes: even if the decision is later reversed, the record that it was made, why, and what was known stays true forever. That's why an ADR isn't "updated": it's superseded (a new one is written that says "replaces ADR-021") and the old one is kept as history. That permanence is what lets it travel through time.

In the capstone, this union is more than a good practice: it's the mechanism that keeps the thread cohesive across time. The diagram communicates the structural decision of step 3; the ADR anchors that decision to step 2 (the governing attribute that justifies it) and to the consequences that steps 6 and 8 are going to manage (the seams, the scalability-vs-cost trade-off). An architect who delivered only the diagram would leave the why in their head —and when they left, the sellers surface would remain a photo with no story, ready for someone to undo through not understanding it—. An architect who delivered only the ADR would leave the reasoning without the photo that grounds it. The complete communication package of an important decision is the diagram that shows the new shape plus the ADR that explains why —and that's exactly what you deliver in this step, and what you'll assemble in the dossier of lesson 8—.

A frontier point, so as not to invade the sister guide. The mechanics of the ADR —how it's structured, when it's written, how it's numbered, how it's superseded, how you decide which option to choose with a matrix— belong to architecture-decisions-and-tradeoffs. Here we don't choose between options (gateway yes or no?, one service or several?); that decision was already made in step 3, derived from the governing attribute. Here we only communicate the already-made decision, writing the ADR with the reader who wasn't in the room in mind. The skill of this step isn't deciding; it's communicating a decision so it survives.

Common mistakes

Putting technology in the Context or classes in the Container (of level leakage). What happens: the change's Context ends up with "Seller API Gateway (Kong)" or "PostgreSQL", losing the VP; or the Container shows "SellerOnboardingController" and "PayoutService" —internal classes of the service, not deployable pieces—. Why it happens: for the architect the technology is the interesting part and it's hard to resist mentioning it. How to spot it: show the Context to someone non-technical; if they ask "what's a gateway?", you put level 2 in level 1. In the Container, ask of each box "is this deployed separately?"; if not, it's a component in disguise. How to fix it: in the Context, business language ("Mercado open to sellers via API"); in the Container, only deployable pieces (the gateway, the seller_platform service, the database); the internal classes are level 3, which is almost never worth drawing.

Writing the ADR "for the file", without the tension or the price (of a formality). What happens: the change's ADR says curtly "We decided to expose a Seller API with a dedicated team. Consequences: better separation", without the context that cites the governing attribute or the conscious price. The future dev doesn't learn why, and undoes the decision through ignorance. Why it happens: the ADR is treated as a compliance requirement, not as a letter to a future reader. How to spot it: if your ADR boils down to "we decided X" without a "because scalability weighed 38 and without an owner there were 21 of friction, and accepting these seams", it's a file, not communication. How to fix it: fill the Context with the real tension (the governing attribute, the measured friction) and the Consequences with the price (the latency, the seams) —precisely what the future reader needs so as not to reopen a closed debate—.

Delivering the diagram without the ADR (of a photo with no story). What happens: the architect delivers an impeccable C4 and leaves, leaving the why in their head. Months later, a dev looks at the gateway and thinks "this is unnecessary complexity, I'll remove it" —without knowing the gateway exists for third-party security (security 30) and to isolate the internal model—. Why it happens: the diagram is tangible and "looks finished", so it seems enough. How to spot it: if your deliverable has the photo (the C4) but not the story (the ADR), you communicated half of it. How to fix it: never deliver an important structural decision only with the diagram; the diagram+ADR pair is the minimum, because the diagram ages and the ADR is what prevents someone from undoing the decision when whoever made it is no longer there to explain it.

Exercises

Exercise 1 — Which map do I give each person? For each situation of the change, say whether you need the Context or the Container, and why: (a) the VP wants a slide to present the change to the board of investors; (b) a dev from an external seller's team asks "what do I integrate against and how?"; (c) the payments lead wants to understand what part of the system the payouts flow will touch before committing their squad.

See solution

  • (a) The VP before the board → Context. The board brings the world's question: what is this change, who uses it, what does it enable? Six boxes without jargon tell the story (external sellers now enter, integrating via API) and fit on a slide. A Container would lose them in gateways and services the board doesn't evaluate.

  • (b) The external seller's dev → Container (and the Seller API contract). They need to know what piece they integrate against and how: the Container shows them the Seller API Gateway as the entry point, with its protocol (JSON/HTTPS) and that seller_platform is behind it. The Context would be too little (they wouldn't see the gateway); what they'll actually use is the contract of the Seller API, which is the gateway's detail. Here the Container is the right level to orient them, and the contract the document that follows.

  • (c) The payments lead → bounded Container. Their question is specific: "what does the payouts flow touch". The Container shows it: seller_platform orders payouts to the external Payment Gateway, and there's the payout ↔ payments seam. They see exactly what contract their squad will have to expose. The Context would be too abstract for such a concrete question about one piece.

The pattern: questions of what it is / who uses it → Context; questions of against what piece and how / what part does this touch → Container. Show the minimum level that answers the question and not one more —the C4's discipline—.

Exercise 2 — Rescue a formality ADR. A team member wrote this "ADR" of the change, complete: "Decision: We create the Seller API with a new team. Consequences: Better organization." A future dev learns nothing useful. Rewrite it so it communicates, citing what the capstone's thread already produced. What was it missing?

See solution

It was missing the two things that make an ADR communicate: the tension in the context (which in the capstone are steps 2 and 3) and the price in the consequences. As it stands, it doesn't say why a new team and not splitting the surface, nor what was sacrificed. A version that communicates:

ADR-021: Dedicated Seller API with a seller_platform team Status: Accepted — 2026-07 Context: We open to external sellers and expect to grow 10x. The governing attribute is scalability (score 38, derived from the goals), and security is second (30) because third parties enter. If the sellers surface is split up by proximity among catalog, orders, payments and platform, it measures 21 pairs of coordination friction and can't scale (every change drags in several squads). It's an architecturally significant decision: it shapes the structure, it's expensive to reverse with third parties already integrated, and it's high-risk. Decision: A public Seller API behind a gateway (third-party auth, rate limiting), and a stream-aligned seller_platform team owning the complete surface. catalog, payments, auth and notifications are consumed as services via a stable contract. Consequences:

  • In favor: an owning team that scales without coordinating (friction 21→7, −67%); the public contract isolates third parties from the internal model.
  • The price: a new team has to be set up (the improvement is the destination, not day one); the gateway adds a hop that clashes with instant_checkout; two genuine seams remain (import listings ↔ catalog, payouts ↔ payments) that require contracts.

Now the future dev understands why the new team (scalability demanded it and without an owner there were 21 of friction), why the gateway (third-party security), and what it cost (latency, two seams). What rescued the ADR is the thread: it cited the governing attribute of step 2 and the measured friction of step 3, which is what turns a decision that "looks like complexity" into an obvious answer to what the business prioritized. A capstone ADR that doesn't cite the previous steps wastes the advantage of having done them.

Exercise 3 — The decision that gets reversed. A year later, Mercado discovers the gateway's latency is slowing the checkout of the biggest sellers, and decides to reverse part of the decision: give those sellers a direct integration without a gateway. A dev proposes "let's delete ADR-021, it no longer applies". Is that right? What do you do, and why does it matter for the capstone?

See solution

It must not be deleted. Deleting ADR-021 destroys the history of why it was made and why it was adjusted. If you delete it, a year from now someone might propose again putting all the sellers behind the gateway —without knowing it was already done, that the latency slowed the big ones, and that's why they were given a direct integration—. They'd repeat the pain. The most expensive knowledge (what we tried and why it didn't work for a certain case) would be lost.

The right thing, per the sister guide's mechanics: mark ADR-021 as partially superseded and write a new ADR —say ADR-034, "Direct integration for high-volume sellers"— that explains the new context (the gateway's latency was slowing the big ones), the new decision (a direct path for that segment) and its relation to the old one ("adjusts ADR-021 for high-volume sellers"). The 021 is kept, now with a status pointing to the 034.

Why it matters for the capstone: the ADR-021 didn't only record a decision —it recorded the price accepted consciously, including "the gateway adds a hop that clashes with instant_checkout"—. When the latency became a real problem, that price was already documented: the team wasn't surprised, because the ADR had warned it. The chain ADR-021 → ADR-034 tells the future the complete story —the gateway was put in for scalability and security, it was adjusted for the big ones for performance—, which is infinitely more useful than either of the two decisions alone. And it confirms the lesson of step 4: writing the conscious price in the consequences isn't pessimism, it's the most valuable gift for the future —it turns a painful revision into an informed evolution, which is exactly what step 6 (planning the evolution) is going to make explicit—. History isn't edited or deleted: it's added to.

Summary and next step

In this lesson you did step 4 of the deliverable: communicating the decision with the C4 and the ADR. With the two maps of the city (the tourist one for the VP, the subway one for the dev) and the note from the previous owner (the ADR), you understood that the diagram communicates the what and the ADR the why, and that an architecture is only truly communicated with both. You drew the Context of the change (6 elements, with the external seller integrating via API) and the Container (12 elements, with the gateway and seller_platform), and you measured that going from zoom 1 to 2 is opening the Mercado box without touching the world around it. And you generated, executed, the ADR-021 as a communication piece —with the tension in the context (which cites the governing attribute of step 2 and the friction of step 3), the price in the consequences (the latency, the two seams), and the status that says whether it still applies—. You understood that in the capstone the ADR is where the thread becomes text: it anchors the structural decision to the previous steps and to the consequences the following steps will manage.

Before moving on you should be able to: draw a Context legible to the business and a Container legible to devs of a change; write an ADR that communicates (tension that cites the why, conscious price, status) and doesn't only file; decide what C4 level corresponds to each audience; and handle a reversed decision without deleting the history.

What follows is step 5, where the communication is put at the service of action. You already have the diagram and the ADR that explain the decision; lesson 6 teaches you to use them to lead the rollout without authority. Because communicating well isn't enough: the squads that must now adopt the contracts of the change (the Seller API one, the platform-as-a-service ones) don't report to the architect, and a well-communicated decision doesn't implement itself. You're going to measure, executed, the genuine adoption that influencing with guardrails achieves (seeding in the early adopter, giving the contract-test that makes it cheap, seeking consensus) against the reflex of the mandate —and see why the architect who orders gets paperwork and becomes the bottleneck that step 1 swore to avoid—.

Resources

← Previous4. Apply the inverse Conway maneuverNext →6. Lead the rollout without authority