architecture-walkthrough
Turn a finished build into a walkthrough a reviewer opens once and understands — published as an HTML artifact with the Artifact tool.
This exists for a specific moment: a change is large enough that reading the diff first is the wrong order. The reviewer needs the shape before the lines. It is the render/explain step downstream of the build and upstream of the review — it presents architecture that already exists, it does not design it.
When to use
- A sizeable change is about to go to a human reviewer, and the review is about judgement rather than line-by-line correctness (often because a bot already did the line-by-line pass).
- Someone asks "explain the architecture of X" or "what are the moving parts here".
- A reviewer has started asking structural questions — where does the worker live, why not put this in the other service — which means the shape was never handed to them.
Not for: designing something not yet built (that is decision-record, which is forward-looking and argues a choice), presenting a defect or incident to a stakeholder (that is incident-report), or splitting work into tasks (that is breakdown).
Pairs well with a short review brief — the agenda and the judgement calls — when there is a meeting. The walkthrough is the reference; the brief is what gets said out loud.
What it needs before it is worth writing
Do not start until these are true, or the document will assert things that are not so:
- The build is finished and verified, not in flight.
- The numbers are measured, not estimated — throughput, limits, row counts, diff size.
- Any claim about existing behaviour being unaffected has actually been checked, ideally against the environment that matters rather than reasoned about.
The spine
Eight sections, in this order. Drop any that does not apply; do not reorder, because each one answers the question the previous one raises.
| # | Section | The question it answers |
|---|---|---|
| 1 | The seam | Where does new code meet old, and what did the old code lose? |
| 2 | The pipeline | How does data actually get from one end to the other? |
| 3 | Where the work runs | Which process, which trigger, and why there rather than elsewhere? |
| 4 | What is stored | The shape, the indexes, and what each index is for. |
| 5 | When it goes wrong | Failure, reversal, and the states a thing can be in. |
| 6 | Couplings | What else reads or writes this, that a reader would not expect. |
| 7 | Limits | Every bound, with the reason it was chosen. |
| 8 | Before deploy | What must exist first, separated by what happens if it does not. |
What makes one of these land
Open with a number the reviewer can check themselves. "2,771 lines added, 4 removed, 0 of them from the dispatch this change is supposed to leave alone" converts a promise into a verifiable fact, in one line, before any prose. Find the equivalent for the change at hand.
Quote the seam, do not describe it. If the central claim is "the existing path is untouched", show the actual lines with the untouched code visible just below, and a marker on the boundary. A reviewer came to verify a claim; a paraphrase gives them nothing to verify.
Draw mechanisms, not org charts. Three figures usually carry a system: the dispatch or decision (what happens on the read side), the pipeline with the boundary crossings numbered (what crosses which trust or process boundary), and a state machine (what a thing can become, including the ugly transitions). Label every arrow with a verb. See mermaid-diagrams when the target is a markdown surface rather than an HTML artifact.
Answer "why not X" before it is asked. Every non-obvious placement invites an alternative. Name the alternatives that were genuinely considered and say what each would have cost — cross-repo duplication, a key spread wider, a concept invented to fit. A reviewer who has to ask this has already lost confidence.
Name the sharp edges yourself. This is the difference between a document that informs and one that sells. If deterministic encryption leaks equality, say so and say why that is the point. If a key is shared with something older, say so. If a stuck record stays visible rather than self-cleaning, say so. If a product decision is expressed in code, mark it as the thing most worth a second opinion. A reviewer who finds an edge you hid stops trusting the rest.
Separate loud failures from quiet ones. In the deploy section, distinguish what prevents a service from starting from what merely degrades a feature. Those get different urgency and often different owners.
Give every limit its reason. A table of numbers is inert. 25 MB — sized for the largest municipality, rejected before anything is read tells a reviewer whether the bound was chosen or inherited.
Format
Published with the Artifact tool as HTML. Load artifact-design before writing so the treatment is decided rather than defaulted, and artifact-diagramming for the figures.
Body in English, matching the PRs, tickets and design docs it sits beside, so it can be handed to the reviewer directly. The conversation about it may be in any language.
Keep it scannable: a reviewer should be able to read only the section headings and the figures and still know the shape. Prose paragraphs earn their place by explaining a why that the diagram cannot.
Related
decision-record— argues a design before it is built; this explains one after.incident-report— same publish mechanics, different subject and audience.cto-review— the deep architectural critique; this is the input that makes such a review cheap.mermaid-diagrams— diagram authoring for markdown surfaces.