Module 7: Documentation That Survives

8. Project: make Mercado's documentation survive

Next →

Overview

In this project you're going to act as Mercado's architect and produce, from start to finish, the documentation package that survives a real and urgent scenario. It's not a new lesson: it's where you assemble everything in the module. The scenario has two blows at once, of the kind any team faces sooner or later: Elena, the only person who understands the payments module, announced she's leaving in a month; and at the same time, the team is going to bring on six new developers this quarter to accelerate. Both blows attack the same thing —the knowledge—: Elena's departure threatens to take the knowledge of payments (bus factor 1), and the arrival of six people demands that the system's knowledge be available so they get going without depending on anyone. Your job is to leave the documentation in a state that survives both blows, and prove it with an executed report.

You deliver four things, each a piece of the module applied to the case: (1) the docs-as-code structure —the arc42 skeleton with the C4 and the ADRs, versioned in the repo, not in a wiki—; (2) the README that onboards the six new devs —that takes them to their first commit without depending on Elena or anyone—; (3) the ADR that captures the stable decision of payments —the why of its design, written now that Elena is there to dictate it, so it survives her departure—; and (4) the ready-to-survive report executed: the doc validated against the code, payments' bus factor raised from 1 to 2, and the onboarding cost with the new README, ending in a verdict. At the end you'll have in your hands exactly what an architect delivers when they have to make a system's knowledge survive a departure and a wave of arrivals.

Connection with the module: this project closes the seven topics. It uses living documentation and docs-as-code (lessons 2-3) to put the doc in the repo and validate it; the C4 + ADR + arc42 system (lesson 4) as the structure of the package; the rule of documenting the stable (lesson 5) to choose what to capture of payments (its why, not its details); the README that onboards (lesson 6) for the six devs; and the bus factor (lesson 7) as the metric that measures whether Elena's departure leaves payments orphaned. At the end, it points to module 8: the guide's capstone, where you'll be Mercado's architect facing a business change, and the documentation that survives will be part of what you deliver.

The file you leave the team before you go

Go back once more to the homeowner —the brick kind— but at a particular moment: the day they move out and hand the house over to the next inhabitants. A good previous owner doesn't just leave; they leave the file that lets the new people operate the house without them: the folder with where each valve is and how each thing lights (so they can live in the house from day one), and a notebook with the why of the strange decisions —"the cistern is on the roof and not below because the street pressure isn't enough; don't move it without solving that first"— (so they don't undo through ignorance what he solved with care). He leaves, but the knowledge of how to operate the house and why it's this way stays, written, available to anyone who arrives.

Your Mercado documentation package is that move-out file, with a crucial difference in timing: you assemble it while Elena is still there —while the grandmother can still dictate the recipe—. The docs-as-code structure and the README are the "how to operate the house" folder (for the six who arrive); the payments ADR is the "why it's this way" notebook (so no one undoes Elena's decision by not understanding it). Elena will leave, as the previous owner moves out; but if the file is well assembled, the knowledge of payments and of how to get Mercado running stays. This project is assembling that file and proving —with numbers— that it really does let you operate the house without the previous owner.

The assignment: Elena leaves, six join, and the knowledge can't leave with her

The context, so you're clear before documenting. Mercado has six modules in the code: catalog, orders, payments, shipping, platform, search. Its knowledge map has two single points of failure —payments (only Elena) and search (only Caro)—, but the urgent one is payments, because Elena already announced she's leaving in a month. At the same time, six new devs join who need to get going fast. The architect already knows what to do in broad strokes: capture the stable of payments before Elena leaves, put the doc in the repo where it won't rot, and give the six a README that makes them autonomous. Your job isn't to re-decide that: it's to produce the package and prove that it leaves the documentation ready to survive Elena's departure.

Deliverable 1: the docs-as-code structure (the skeleton in the repo)

The first thing is where the doc lives: in the repo, next to the code, in plain text, reviewed in PRs and validated in CI —docs-as-code (lesson 3)—, organized with the arc42 skeleton (lesson 4). Not in a wiki that rots. Here's how the structure looks in the repo:

mercado/
├─ src/                         <- the code (the source of truth)
│   ├─ catalog/  orders/  payments/  shipping/  platform/  search/
├─ docs/                        <- the doc, versioned WITH the code
│   ├─ README.md                <- onboarding (deliverable 2)
│   ├─ architecture/            <- arc42 skeleton
│   │   ├─ 01-context.md         · C4-Context (the map of the world)
│   │   ├─ 05-building-blocks.md · C4-Container (the pieces)
│   │   ├─ 09-decisions/         · the ADRs (the why)
│   │   │   ├─ adr-014-*.md
│   │   │   └─ adr-030-payments-separate.md   <- deliverable 3
│   │   ├─ 10-quality.md         · quality attributes and goals
│   │   └─ 11-risks.md           · risks and debt (incl. bus factor)
│   └─ diagrams/                 <- PlantUML/Mermaid (text, diffable)
└─ .ci/
    └─ validate_docs.py          <- the validator (lesson 3): breaks the build

Notice three decisions, each a lesson of the module. The doc lives in docs/, inside the same repo as src/ (docs-as-code): the PR that changes payments also touches its doc, and the reviewer sees both things together —impossible for them to silently desync—. The structure follows arc42 (the skeleton of lesson 4): each kind of knowledge has its place —the C4 in context and blocks, the ADRs in decisions, the risks in their section— and the absences are visible (an empty section screams that something's missing). There's a validate_docs.py in CI (the validator of lesson 3): it cross-checks what the doc claims against the code's modules and breaks the build if there's a broken reference or an undocumented module. The doc can't rot silently, because its synchronization is a test.

Deliverable 2: the README that onboards (for the six who arrive)

The six new devs need to get going without depending on Elena. The README answers the four questions of lesson 6 —what it does, how to run it, where the pieces are, how to contribute— with the "how to run it" tested on a clean machine:

# Mercado — Internal API

Marketplace connecting buyers and sellers. This repo is the Internal API
(catalog, orders, checkout, payments, shipping, search).

## How to run it (tested on a clean machine)
1. `cp .env.example .env`      # copy the variables; secrets go in 1Password (see #infra)
2. `docker compose up -d`      # brings up PostgreSQL, Redis and Elasticsearch
3. `make dev`                  # installs dependencies and runs the API on :8000
4. `make test`                 # runs the tests; they should all pass green
If something fails here, it's a README bug: report it in #mercado-dev and we fix it.

## Where the pieces are
Full map in docs/architecture/05-building-blocks.md (C4-Container).
In one line: catalog (products) · orders · payments (charges) ·
shipping · platform (auth, shared infra) · search.

## How to contribute
Branch -> PR -> review by a module owner -> merge. CI runs tests AND validates the doc.
A module's doc is updated in the SAME PR that changes it (docs-as-code).

How you tell it to the six: "With this you get going on your own. Follow the 'how to run it' exactly; if a step fails, it's not that you did something wrong —it's a README bug and we fix it, because the README has to work on a clean machine—. The map of pieces tells you where to go; the why of each piece is in the ADRs. And watch the last rule: a module's doc is updated in the same PR that changes it, so it doesn't rot." With this README, the six reach their first useful commit in hours, without consuming anyone —and without depending on Elena, who's already leaving—.

Deliverable 3: the ADR that captures the stable decision of payments

This is the deliverable that races against the clock: capturing the why of payments while Elena is still there to dictate it. It's the stable (lesson 5), what isn't in the code, what gets lost most when someone leaves (lesson 7). The ADR:

# ADR-030: Payments is a separate service, with queued charging

Status: Accepted | Date: 2026-07-30 | Deciders: Elena (payments owner), architect, platform lead

## Context Payments charges the money: it's the most delicate module in the system. It receives traffic from checkout (internal) and, in the future, from external sellers. An error or a spike that takes it down doesn't only lose money: it can leave charges half-done, a corrupt state that's very expensive to reconcile. Also, the payment logic has business and compliance rules (refunds, retries, idempotency) that must not be mixed with the rest.

## Decision Payments is a separate service from the core, with its own boundary: no one reads or writes its tables directly; you talk to it through a clear interface. The charges aren't processed synchronously in the checkout: they're queued and payments processes them at its own pace, with idempotent retries, so that a checkout spike doesn't take it down and a failure doesn't leave a charge half-done.

## Consequences In favor:

  • Checkout's traffic and spikes can't take down or corrupt payments: the queue buffers and isolates.
  • Payments can be scaled, protected, and audited separately, with its compliance rules contained.

Against (the price we accept):

  • The charge isn't instant: it goes through the queue, there's a delay until confirmation. We accept it because the integrity of the money is worth more than immediacy.
  • One more piece and one more queue to operate, and the complexity of idempotency.

This ADR is the "why it's this way" notebook that Elena leaves the team. When a year from now a new dev —one of the six who arrive— sees the payments queue and thinks "this would be simpler if the checkout charged directly", the ADR will tell them: yes, we knew; the delay is the conscious price of not letting a spike take down the money, and of not leaving charges half-done. They won't undo Elena's decision through ignorance. The why —the stable, what was going to leave with Elena— stayed written, dictated by her while she was there. That's the grandmother's recipe, captured in time.

Worked example: the ready-to-survive report

Before calling the package good, you run it through a report that measures the three things that matter for the scenario: is the doc synced with the code (docs-as-code)? does payments' bus factor stop being 1 when we document it, so Elena's departure doesn't leave it orphaned? is the onboarding of the six cheap with the new README? The report runs all three and gives a verdict:

# Project: make Mercado's documentation SURVIVE. Scenario: Elena, the sole knower
# of 'payments', leaves in a month; and 6 new devs join this quarter.
# We produce the ready-to-survive report: (1) validate the doc against the code,
# (2) measure the bus factor and who Elena takes with her, (3) measure the onboarding cost
# with the new README, and give a VERDICT.
CODE_MODULES = {"catalog", "orders", "payments", "shipping", "platform", "search"}
OWNERSHIP = {
    "catalog":  {"Ana", "Beto", "Caro"},
    "orders":   {"Beto", "Diego"},
    "payments": {"Elena"},
    "shipping": {"Diego", "Caro"},
    "platform": {"Ana", "Elena", "Beto"},
    "search":   {"Caro"},
}

# --- 1) The doc versioned in the repo, validated against the code (docs-as-code) ---
DOC_REFERENCES = {
    "ADR-014":                   {"orders", "payments"},
    "ADR-030-payments-separate": {"payments", "orders", "platform"},
    "C4-container":              {"catalog", "orders", "payments", "shipping", "search"},
    "README":                    {"catalog", "orders", "payments", "shipping",
                                  "platform", "search"},
}
documented = set().union(*DOC_REFERENCES.values())
broken = sum(len(refs - CODE_MODULES) for refs in DOC_REFERENCES.values())
undocumented = CODE_MODULES - documented
doc_ok = (broken == 0 and not undocumented)
print("== 1) Docs-as-code: validation against the code ==")
print(f"  broken references: {broken}")
print(f"  undocumented modules: {len(undocumented)}")
print(f"  -> {'PASS' if doc_ok else 'FAIL'}")

# --- 2) Bus factor and the single point of failure Elena would take ---
print("\n== 2) Bus factor before Elena leaves ==")
at_risk = [m for m, o in OWNERSHIP.items() if len(o) <= 1]
elena_orphans = [m for m, o in OWNERSHIP.items() if o - {"Elena"} == set()]
print(f"  modules at risk (bus factor 1): {at_risk}")
print(f"  if Elena leaves TODAY, orphaned: {elena_orphans}")
STABLE_DOC = {"payments"}   # we document its boundaries + the ADR-030 decision


def eff_bf(m):
    return len(OWNERSHIP[m]) + (1 if m in STABLE_DOC else 0)


print("  we document the STABLE of 'payments' (ADR-030 + boundaries):")
print(f"    payments: bus factor {len(OWNERSHIP['payments'])} -> {eff_bf('payments')}")
elena_orphans_after = [m for m in elena_orphans if eff_bf(m) <= 1]
print(f"    if Elena leaves now, orphaned: {elena_orphans_after}")

# --- 3) Onboarding cost of the 6 new devs with the new README ---
print("\n== 3) Onboarding of 6 new devs with the README ==")
BLOCKERS = [
    ("run the project",  8.0, 0.5),
    ("locate the pieces", 6.0, 0.5),
    ("configure the env", 4.0, 0.25),
    ("run the tests",     3.0, 0.25),
    ("where to change",   5.0, 1.0),
    ("PR flow",           2.0, 0.1),
]
without = sum(w for _, w, _ in BLOCKERS)
with_ = sum(c for _, _, c in BLOCKERS)
NEW = 6
print(f"  time to first commit: without README {without:.0f}h -> with README {with_:.1f}h")
print(f"  saving with {NEW} devs: {(without - with_) * NEW:.0f}h this quarter")

# --- Verdict ---
print("\n== VERDICT: ready to survive Elena's departure? ==")
survives = doc_ok and not elena_orphans_after
print(f"  doc synced with the code: {'yes' if doc_ok else 'no'}")
print(f"  payments NOT orphaned if Elena leaves: {'yes' if not elena_orphans_after else 'no'}")
print(f"  cheap onboarding for the new devs: yes ({with_:.1f}h vs {without:.0f}h)")
print(f"  -> DOCUMENTATION {'SURVIVES' if survives else 'DOES NOT SURVIVE YET'}")
print("  (honest pending: 'search' is still at bus factor 1 -> the next insurance)")

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

== 1) Docs-as-code: validation against the code ==
  broken references: 0
  undocumented modules: 0
  -> PASS

== 2) Bus factor before Elena leaves ==
  modules at risk (bus factor 1): ['payments', 'search']
  if Elena leaves TODAY, orphaned: ['payments']
  we document the STABLE of 'payments' (ADR-030 + boundaries):
    payments: bus factor 1 -> 2
    if Elena leaves now, orphaned: []

== 3) Onboarding of 6 new devs with the README ==
  time to first commit: without README 28h -> with README 2.6h
  saving with 6 devs: 152h this quarter

== VERDICT: ready to survive Elena's departure? ==
  doc synced with the code: yes
  payments NOT orphaned if Elena leaves: yes
  cheap onboarding for the new devs: yes (2.6h vs 28h)
  -> DOCUMENTATION SURVIVES
  (honest pending: 'search' is still at bus factor 1 -> the next insurance)

Read the report section by section, because each is a piece of the module proven on the case.

Section 1: the doc passes validation. Zero broken references and zero undocumented modules —unlike the validator of lesson 3, which failed, here the package you assembled is synced: everything the doc claims exists in the code, and every module in the code (including platform, which in lesson 3 was undocumented) has doc—. The doc is in the repo, validated in CI, green. Docs-as-code fulfilled: the doc won't rot silently.

Section 2: payments' bus factor stops being 1. The report confirms the diagnosis: payments and search are at bus factor 1, and if Elena leaves today, payments is orphaned. Then it applies deliverable 3 —documenting the stable of payments (ADR-030 and its boundaries)—, and payments' bus factor rises from 1 to 2. Now, if Elena leaves, the list of orphans is empty: []. That's the heart of the project, measured: Elena's departure no longer leaves payments without an owner, because its stable knowledge was captured in time. The recipe was written while the grandmother was there.

Section 3: the onboarding of the six is cheap. With the README of deliverable 2, the time to the first useful commit drops from 28h to 2.6h per dev, and with the six who join that's 152 hours saved this quarter —almost a person-month that, without a README, would burn on discovering the system the hard way—. The six get going on their own, without depending on Elena who's leaving or on anyone.

The verdict: DOCUMENTATION SURVIVES. The three conditions are met —doc synced, payments not orphaned if Elena leaves, cheap onboarding— so the package leaves Mercado ready to survive Elena's departure and the arrival of the six. But notice the last line, and it's deliberate: the honest pending —search is still at bus factor 1—. The verdict is about surviving Elena's departure specifically (the urgent blow), not about eliminating all risk. search, which only Caro maintains, is still a single point of failure, and the next insurance to buy is documenting the stable of search before Caro leaves. An honest architect doesn't declare "everything solved"; they declare "the urgent blow solved, and here's the next risk in line". That honesty —measuring what was achieved and naming what's missing— is part of the craft.

Common mistakes

Documenting payments in panic on the last day (late). What happens: the team waits until Elena is about to leave and, in her last week, tries to extract all of payments' knowledge in rushed handover sessions. It comes out incomplete: Elena already has one foot out, the tacit knowledge doesn't surface under pressure, and what's documented is low quality. Why it happens: while Elena was there, documenting payments didn't seem urgent (she knew), so it was postponed until it became urgent and almost too late. How to spot it: if a critical module's documentation is being done after its sole owner's departure announcement, you're already late. How to fix it: capture the stable of the bus factor 1 modules now, while their owners are in full form and use the knowledge daily —the insurance premium is paid before the departure (lesson 7), not in the last week—.

Putting the doc in a wiki "to share it with the six" (far from the code). What happens: thinking of the six new devs, the team writes the doc in a pretty wiki "so it's easy to find and share", separate from the repo. It rots exactly as in lessons 2 and 3, and by the time the second group of devs arrives, the doc already lies. Why it happens: the wiki seems more "shareable" and presentable than Markdown files in the repo. How to spot it: if your onboarding package lives outside the repo, you can't validate it or review it in the PRs, and it's going to desync. How to fix it: the doc lives in the repo (docs-as-code); it "shares" just as well (the six clone the repo and it's all there), and moreover it stays alive through proximity and validation. The comfort of the wiki is the trap the whole module dismantles.

Declaring "everything solved" and hiding the pending (dishonesty). What happens: the team insures payments, sees the verdict SURVIVES, and reports "Mercado's documentation is solved" —hiding that search is still at bus factor 1—. Months later Caro leaves, search is orphaned, and no one saw it coming because the report said "all good". Why it happens: it's more comfortable (and looks better) to report a complete success than a partial success with a pending. How to spot it: if your report doesn't explicitly name the risks you didn't solve, you're hiding the next blow. How to fix it: every honest verdict names its scope and its pending —"the Elena/payments risk solved; the Caro/search one still open, and it's the next insurance to buy"—; the bus factor is a radar to leave on, not to turn off after the first fix. An architect reports what they achieved and what's missing.

Exercises

Exercise 1 — Assemble the package for the next risk. The report left an honest pending: search is still at bus factor 1 (only Caro). As the architect, assemble the skeleton of the package to insure search before Caro leaves: (a) which deliverable of the module is the most urgent and why?; (b) what decision of search would deserve an ADR?; (c) how would you verify it with the report?

See solution

(a) The most urgent deliverable is the ADR that captures the stable of search (its why and its boundaries), done while Caro is still there. It's the same as with payments: the stable (the why, the boundary) is what isn't in the code, what gets lost most when Caro leaves, and what raises the bus factor from 1 to 2 cheaply (lesson 7). And it's urgent for the same temporal reason: you have to write the recipe while the grandmother is there, not in her last week. The README and the docs-as-code structure already exist from the previous package; what's specifically missing for search is capturing its stable knowledge.

(b) The decision of search that would deserve an ADR: for example, "why search uses a separate index (Elasticsearch) instead of querying the database directly" —a decision with a real trade-off (the index gives fast, relevant search but adds a piece that has to be synced and that can go stale relative to the database)—. Or "how the index stays synced with the catalog, and what happens if it desyncs". Anything that has a why with a price that a future dev would want to understand before changing it. That why is exactly what would leave with Caro if it's not written.

(c) How I'd verify it with the report: I'd run the same ready-to-survive report, but simulating Caro's departure instead of Elena's, and with STABLE_DOC = {"payments", "search"} (now both documented). I'd expect to see: search in the risk list dropping to bus factor 2 after documenting it; "if Caro leaves, orphaned: []"; and the verdict SURVIVES also for Caro's departure. With both modules insured, the whole system would stop having single points of failure —the system's bus factor would rise from 1 to 2 (lesson 1)—. The report is the way to prove that the new insurance works, not just claim it.

Exercise 2 — Spot the badly assembled package. A colleague hands you their package for the same scenario (Elena leaves, six join): they documented payments in depth in a Confluence wiki of 40 pages that include every endpoint and every function signature; they wrote no ADR ("the diagrams explain everything"); and they didn't touch the README ("the six can ask the team how to get going"). Without running code, diagnose what's wrong using the lessons of the module, and say how you'd redo it.

See solution

Diagnosis:

  • Wiki in Confluence, far from the code (lessons 2-3): the doc separate from the repo is going to rot —it can't be reviewed in the PRs or validated in CI, so it'll desync release by release until no one trusts it—. Also, it's not docs-as-code: there's no validator to break the build if the doc lies.
  • 40 pages with every endpoint and signature (lesson 5): they documented the volatile in depth. Endpoints and signatures change all the time (high churn, negative ROI); those 40 pages will be obsolete in weeks. They spent the effort on what survives least.
  • No ADR (lessons 4-5-7): they didn't capture the why of payments —the stable, what isn't in the code, what gets lost most when Elena leaves—. "The diagrams explain everything" is false: a diagram shows the what, never the why. Precisely what was going to leave with Elena went uncaptured.
  • README untouched (lesson 6): "let them ask the team" keeps onboarding dependent on people —it consumes the team and doesn't raise the bus factor of the operational knowledge—. The six will take 28h each to get going, and depending on people.

How I redo it: I invert the priorities. (1) I move the doc to the repo (docs/), in Markdown, validated in CI —docs-as-code—. (2) I delete the 40 pages of volatile endpoints and signatures; that's generated from the code (OpenAPI) or read there. (3) I write the payments ADR —its why and its boundaries, the stable— with Elena, now that she's there: it's the urgent thing and what raises the bus factor. (4) I write the README with the "how to run it" tested, so the six get going on their own. (5) I run the ready-to-survive report to prove that payments isn't orphaned and that the onboarding is cheap. The package goes from "40 volatile pages in a wiki that rots, with no why and no onboarding" to "the stable in the repo, validated, with the why captured and the six autonomous" —from a lot of doc that doesn't survive to a little doc that does—.

Exercise 3 — The script of the conversation with Elena. You have a week with Elena before she leaves, and her time is scarce (she's closing out loose ends). Write, in four or five sentences, the script of how you use that time to capture what really matters of payments —applying the stable-vs-volatile rule— without wasting her last week on what can be recovered another way.

See solution

A script that makes the most of Elena's scarce time by focusing it on the stable and unrecoverable:

  1. I ask Elena for the why, not the what. "Elena, I don't need you to explain every function of payments —I read that from the code—. I need you to explain the decisions: why it's separate, why the queue instead of direct charging, what problems you solved that aren't obvious." (I focus her time on the stable that isn't in the code and that would leave with her.)
  2. We write the ADR-030 together as we talk. "We're going to write this now, here, in an ADR in the repo —you dictate the why and the consequences, I type—; that way your reasoning stays in your words, versioned, forever." (I capture the why in time, docs-as-code.)
  3. I ask her about the scares —the tacit. "What are you afraid someone will touch in payments without understanding it? What looks like a bug but is on purpose? Where are the loose wires?" (I extract the tacit knowledge —the grandmother's tricks— that only surfaces by asking, and I note it in the ADR and in the risks section.)
  4. I DON'T spend her time listing endpoints, signatures, or configuration. That's volatile and recovered from the code; asking her for it would waste her last week on what matters least and survives least.
  5. I close by validating that a new dev can follow the trail. "I leave the ADR linked from the README and the C4, so the next person who touches payments finds the why before changing anything." (I connect the captured why with the onboarding of the six.)

The key: Elena's last week is a very scarce resource, and it's spent on the stable and unrecoverable —the why, the scares, the tacit—, not on the volatile that's read from the code. Writing the recipe with the grandmother is asking her what only she knows and isn't anywhere, not asking her to copy by hand what's already written in the kitchen.

Summary: what you built and where it goes next

In this project you assembled the documentation package that survives a real scenario —Elena leaves in a month, six devs join— applying the whole module. You produced the docs-as-code structure (the arc42 skeleton with C4 and ADRs in the repo, validated in CI, not in a wiki), the README that onboards (so the six get going on their own, with the "how to run it" tested), and the ADR-030 that captures the stable decision of payments —its why, written while Elena was there to dictate it, so it survives her departure—. And you proved the package with the ready-to-survive report: the doc passes validation (synced with the code), payments' bus factor rises from 1 to 2 (no longer orphaned if Elena leaves), and the onboarding drops from 28h to 2.6h per dev (152h saved). The verdict: DOCUMENTATION SURVIVES —with the honest pending named: search is still at bus factor 1, the next insurance—. That's the real deliverable of an architect who makes knowledge survive: not a huge wiki, but the stable in the repo, validated, with the why captured in time and the new people autonomous, measured and with its pending in plain sight.

With this you close module 7. You now know how to document so the knowledge survives: understand why doc rots and what keeps it alive, put it in the repo with docs-as-code and validate it in CI, assemble the C4 + ADR + arc42 system, document the stable and not the volatile, write the README that onboards, and measure and raise the bus factor so the system doesn't depend on a single head.

Where it goes next. Module 8 is the capstone of the whole guide: you'll take the role of Mercado's architect facing a real business change —opening Mercado to external sellers via API and growing 10x— and you'll travel the whole craft at once: you'll derive the quality attributes from the goal (module 5), apply the inverse Conway maneuver to structure the teams (module 2), produce the C4 and the ADR that communicate the decision (module 3), explain the trade-off to the stakeholder (module 5), plan the evolution (module 6) —and document everything so it survives (this module)—. Documentation that survives isn't an add-on at the end; it's what makes all the architect's work —the decisions, the boundaries, the why— last beyond whoever did it. The capstone joins the pieces; this was the one that guarantees they aren't lost.

Resources

← PreviousBus factor and knowledge sharingNext →1. Capstone presentation: the craft as one single movement