The Solution Design Document

The idea in one minute#

The solution design document is where an architect’s work becomes something other people can approve, build and blame. It answers, in order: what problem, for whom, how well it must work, what will be built, why this way and not another, what it costs, what could go wrong, and what happens next.

Three techniques make it good. Write for the reader who will only read the first page. Draw with the C4 model — the same system at three zoom levels, so the executive and the engineer each get a picture at their level. And record every significant choice as an architecture decision record (ADR): one page with the context, the decision, the options you rejected and the consequences.

A design document is not judged by its length. It is judged by whether someone who disagrees can find the exact sentence to disagree with.

A picture#

flowchart TB
  subgraph DOC["Solution design document"]
    direction TB
    S1[":i-file-text: <b>1. Summary and decision asked</b><br/><small>one page</small>"]
    S2[":i-search: <b>2. Problem, users, baseline</b>"]
    S3[":i-list-checks: <b>3. Requirements and non-goals</b>"]
    S4[":i-layers: <b>4. Solution</b><br/><small>context → containers → key flows</small>"]
    S5[":i-git-branch: <b>5. Decisions</b><br/><small>ADRs</small>"]
    S6[":i-flask-conical: <b>6. Evaluation plan</b>"]
    S7[":i-coins: <b>7. Cost and business case</b>"]
    S8[":i-shield-alert: <b>8. Risks and controls</b>"]
    S9[":i-route: <b>9. Delivery plan and gates</b>"]
    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9
  end
  EX[":i-building-2: Sponsor"] -.->|"reads"| S1
  EX -.-> S7
  EN[":i-code: Engineers"] -.->|"read"| S3
  EN -.-> S4
  EN -.-> S5
  RK[":i-shield-check: Risk owners"] -.->|"read"| S6
  RK -.-> S8
  class S1 neutral
  class S2,S3 queue
  class S4,S5 compute
  class S6,S7 memory
  class S8 warn
  class S9 io
  class EX,EN,RK neutral

How it really works#

The nine sections#

Ten to fifteen pages for a real system. If it is forty, the summary is doing its job and the rest is an appendix.

Write the first page last, and best#

Most readers stop at page one. It must stand alone.

SUMMARY                                                      Decision needed by 31 Oct

Problem     Claims handlers spend 25 minutes per claim reading documents. Decisions
            take 9 days against a 5-day service standard.

Proposal    Extract the decision facts from claim documents automatically and show them
            to the handler beside the source page. The handler confirms and decides.

Why this    Lowest-risk design that removes the bottleneck: the model reads, the person
            decides. No change to who is accountable for a claim.

Cost        $570k to build and roll out; $560k a year to run.
Benefit     $1.3M a year realised at expected adoption. Payback in about 9 months.

Risks       1. Handwritten documents read poorly → measured in pilot; fallback to manual
            2. Handlers stop checking → sampled audit; source shown beside every field
            3. Customer data to a model provider → in-region processing, no retention

Ask         Approve a 12-week pilot with 15 handlers. Gate: ≥ 97% field accuracy and
            reading time ≤ 6 minutes, measured, before wider rollout.

Four rules for this page: lead with the problem, not the technology; put the number next to every claim; say what you are not proposing; end with a specific ask and a date.

Draw at three zoom levels#

The C4 model — context, containers, components, code — is a simple discipline for diagrams. An architect needs the first two levels and occasionally the third.

Then add one sequence: a single request traced from start to finish, numbered. It catches more design errors than any static picture.

Diagram habits that prevent arguments:

• A title and a date on every diagram.
• A legend if shapes or colours mean something.
• Arrows labelled with what flows and how — “claim documents, HTTPS”.
• A boundary line wherever trust changes: your network, the provider’s, the user’s device.
• Every data store marked with what it holds and how sensitive it is.

Architecture decision records#

An ADR captures one decision so that the reasoning survives after everyone has forgotten the meeting. Keep them short, number them, never edit an accepted one — supersede it with a new one.

ADR-004  Retrieval of policy wording uses hybrid search on the existing search service
Status   Accepted, 9 Oct 2026            Deciders: architect, platform lead, security

Context
  Extraction must cite the policy clause that applies to each claim. Policy documents
  are 12,000 PDFs, updated weekly. Clause numbers are exact strings; customers describe
  events in their own words.

Decision
  Use hybrid (keyword + vector) search on the search service already operated by the
  platform team, with a reranker over the top 50 results.

Options considered
  A. Vector-only search in a new vector database — rejected: misses exact clause numbers;
     a new system to operate and secure.
  B. Put all policies in the prompt — rejected: 12,000 documents do not fit.
  C. Hybrid on the existing service — chosen.

Consequences
  + No new data store to approve. Reuses existing access controls.
  − Dependent on the platform team's upgrade schedule.
  − Reranker adds about 150 ms and a second model to evaluate.

Revisit if
  Retrieval recall on the evaluation set falls below 95%, or the policy set exceeds
  100,000 documents.

The two fields people omit are the ones that make it valuable: options considered shows the decision was a choice, and revisit if tells the next architect when it is safe to change.

Decisions that deserve an ADR in nearly every AI design:

The risk table#

#  Risk                                 L  I  Control                               Owner
1  Wrong extracted amount accepted      M  H  Source shown beside field; 0.5%       Claims Ops
                                              threshold; weekly sampled audit
2  Injected instructions in a document  M  H  Extraction has no tools; output is    Security
                                              schema-validated data only
3  Provider outage in business hours    L  M  Fallback model; 2 h queue; manual     Platform
                                              path documented
4  Model retired by provider            H  L  Model behind gateway; eval rerun on   Architect
                                              each release
5  Handlers reject the tool             M  H  Co-design with 6 handlers; pilot      Sponsor
                                              feedback loop

List the risks that are specific to this design. Twenty generic risks copied from a template hide the three that matter.

The delivery plan and its gates#

A plan is phases separated by gates — measurable conditions for moving on. The gates come straight from the requirements.

Phase            Weeks   Gate to pass
Prototype          3     Extraction works on 50 sample claims; token cost within 2× estimate
Evaluation build   3     Evaluation set of 400 claims agreed with Claims Ops
Pilot             12     ≥ 97% field accuracy; reading time ≤ 6 min; no severity-1 incident
Limited release    8     Same metrics on 40% of volume; cost per claim ≤ $0.08 median
Full release       —     Steering group decision on the pilot report

How those gates are designed is the subject of PoC to Production.

Review it before others do#

Before sending the document, read it as each of the three audiences.

Remember this#

• Nine sections; the first page stands alone and ends with a specific ask.
• Three zoom levels — context, containers, components — and one traced request.
• One ADR per significant decision, with the rejected options and a “revisit if”.
• Risks specific to this design, each with a control and a named owner.
• A plan is phases with measurable gates, taken from the requirements.

Try it#

1. Write the one-page summary for a use case you scored earlier. Give it to someone outside the project and ask what they think they are approving.
2. Write an ADR for a technical decision you made recently. Include two options you rejected and a “revisit if” condition.
3. Draw the context and container diagrams for the same system. Trace one request through the container diagram and number each step.

Check yourself#

1. Who reads which sections of the design document?
2. What do the first two levels of the C4 model show, and who is each for?
3. Which two fields make an ADR worth keeping?
4. What is a gate, and where do its thresholds come from?

Sources#

• The C4 model for visualising software architecture
• Architecture decision records — templates and practice
• arc42 — a fuller documentation template when you need one