Stop 2 of 10 · Weekly
Discovery to architecture
Two hours of discovery notes become an architecture document, a diagram written as code and a decision log where every choice carries the alternative it beat.
Two hours of notes, one weekend of writing
Fadi runs a discovery workshop with Calverton County: four sessions, the records division, the database team, the security officer, the integrator. He leaves with fourteen pages of notes and a deadline. Turning those notes into an architecture document, a diagram and a defensible set of choices is the weekend that never happens, so the document ships thin and the decisions get made in email later.
The notes are the input Claude is best at. They are unstructured, repetitive, contradictory in places, and every fact in them is exactly the sort of thing that has to be read twice. Redact them first, to the rules in stop one: roles not hostnames, volumes not rows, systems not addresses.
Three artefacts from one pass
| Artefact | What it has to survive |
|---|---|
| Architecture document | A security review, an integrator who disagrees, and a new architect in month nine |
| Diagram as code | The design changing four times before the design is final |
| Decision log | The question of why we did not just lift and shift |
Ask for all three in one pass, from the same notes, so they cannot disagree with each other. Then read the document before the diagram, because a wrong diagram drawn from a wrong document is two corrections.
Attached are my redacted discovery notes from four sessions with Calverton County, a county government retiring an on-premises records platform. I am the cloud architect on the account. Write the architecture document with these sections: business context, requirements, constraints, current state, target state, data flows, identity and access approach, network approach described by pattern rather than by address, resilience and recovery targets, and open questions. Mark every requirement as stated, inferred or missing. Stated means it appears in the notes and you can quote the line. Inferred means you concluded it from context, and you say from what. Missing means a section needs it and the notes are silent. List the missing ones together at the end so I can take them back to the county.
From the target state section you just wrote, give me a Mermaid diagram of the Calverton County solution: the environments, the managed database tier, the object storage tier, the identity path from the county directory, and the connectivity to the single on-premises site. Use placeholders for anything that would be an address or an account identifier. Then give me a second, simpler version with at most nine boxes for the executive briefing deck, and tell me what you dropped between the two and why it was safe to drop.
Two diagrams matter more than they sound. The detailed one goes in the document; the nine-box one goes in the deck the county CIO actually reads. Drawing them separately is how they end up describing different systems.
The decision log
One entry per decision, in the document and in the repository. Context, the decision, the alternatives with the reason each was rejected, the consequences accepted, and the trigger that would make Fadi revisit it.
For each architectural choice in the document, write a decision log entry: context, decision, the alternatives considered with a one-line reason each was rejected, the consequences we are accepting, and the condition that should make me revisit this. Be honest in the consequences. If a choice makes the county more dependent on one service, or makes exit harder, or costs more to run than the alternative, say so in the entry rather than in a footnote. Flag any decision where the notes do not actually support the choice I made.