Solution Architecture Document From Specs

Start with who has to accept it, because that reader sets the depth. A review board wants to see each requirement met, an auditor wants evidence behind every security claim, and a new team wants to know what runs where. Then write the scope as two lists: what the solution covers and what it leaves out.

Whatever template you start from, check that it covers the parts below. If you're proposing a change rather than documenting a solution, an RFC and design doc template suits the job better.

Write from the evidence, not from memory. Before you draft anything, collect what already exists and note where each piece came from.

1. 1

   Collect the artifacts

   Diagrams, API specs such as OpenAPI files, infrastructure code, requirements, and the contracts or emails that set constraints.

2. 2

   Date each one

   A diagram from two years ago is history, not fact. Record each file's date and owner.

3. 3

   Check drawings against config

   Infrastructure and deployment files are usually closer to what runs than a diagram drawn once. Compare them.

4. 4

   Log every disagreement

   Where two artifacts conflict, keep both versions with their sources, and say which you trust and why.

Quality goals are what the design is built for, such as availability, security or ease of change. arc42, a free architecture template from Peter Hruschka and Gernot Starke, asks for the top three (max five) quality goals¹ and warns not to confuse them with project goals. Rank yours, and say which one gives way when two conflict.

The Architecture Tradeoff Analysis Method (ATAM), described in a 2000 report from Carnegie Mellon's Software Engineering Institute, shows how. It refines each quality into specific scenarios, then rates each one twice: for importance to the system's success and for the risk of achieving it². The authors prefer High, Medium or Low, because they find stakeholders can't reliably make finer distinctions.

Then make each goal testable, so anyone can tell whether it's met. A line like "The architecture shall be modifiable and robust" fails, the same report says, because it has no operational meaning and can't be refuted. arc42 asks instead for scenarios that are specific and measurable³. Usage scenarios describe how the system reacts to a stimulus. Change scenarios describe a modification and measure the effort or time it takes.

Draw the context view first. It shows your system as one box, surrounded by its users and the outside systems it talks to, with no technology, so a client can follow it. The container view then zooms inside that box.

Pitch the container view at the right level. In Simon Brown's C4 model, a container isn't a Docker container. It's an application or a data store that needs to be running for the system to work⁴, such as a web app or a database. Leave clusters, load balancers and failover to a separate deployment view.

Label every line. C4's notation guide asks for labels that match each relationship's direction and intent⁵, ideally not a single word like "Uses". Lines between containers should also name the technology or protocol. "Sends position updates (JSON over HTTPS)" tells a reviewer something. A bare arrow doesn't.

Record each significant decision with its reasons. Michael Nygard's 2011 essay on architecture decision records⁶ warns that a newcomer who doesn't know why a decision was made can only accept it blindly or change it blindly. His record has five parts (title, context, decision, status and consequences), and it lists every consequence, not just the good ones.

An architecture decision record template keeps your decisions in one register. Sort everything else into three lists, because each needs a different answer:

• Constraints are imposed. Name who imposed each one: "Keep the existing Postgres until the contract renews" (client IT team).
• Assumptions are bets. Name who can confirm each one: "Under 5,000 devices in year one" (client's operations lead).
• Risks are what could go wrong, and what it would cost: "If the map provider throttles requests, positions arrive late."

Give security its own section: who can reach what, how data is protected, and the main threats. If the review turns on security, work through a STRIDE threat model first and summarize it here.

Traceability lets a reviewer check the design instead of nodding along. NASA's Systems Engineering Handbook calls for bidirectional traceability between customer requirements, design documents and test plans⁷. It says a requirement with no parent, unless the team derived it and had it accepted, points to a flawed trace or to "gold plating" that should be eliminated.

Run your map in both directions. Down: each requirement, the component that meets it and the artifact that proves it. Up: each component and the requirement it exists for. A requirement with no component is a gap, so list gaps first. A component with no requirement is scope nobody asked for, or a decision nobody wrote down.

Starting from a folder of specs and old diagrams? The tool at the top of this page reads them, builds the two-way map and drafts the document, with every claim tied to the file it came from.