Solution Architecture Document: What to Include (+ Template)

A solution architecture document explains what problem is being solved, what constraints apply, which options were considered, what was chosen and why, and how the chosen design works: its systems, integrations, and data. A good one is short enough that people actually read it, and specific enough that a team can build from it.

The mistake I see most is documents that describe the chosen design in detail but never say what else was considered. Six months later, nobody remembers why it was built that way, and the same debate starts again.

What to include

1. Context and problem

Two or three paragraphs. What is happening today, who is affected, and what “solved” looks like. If people can’t agree on this section, stop and resolve that before designing anything.

2. Scope

What this design covers, and just as importantly, what it doesn’t.

3. Requirements

• Functional: what the solution must do.
• Non-functional: performance, availability, security, compliance, and scalability expectations, with numbers wherever you have them.

4. Constraints and assumptions

Budget, deadlines, existing systems that can’t change, regulation, team skills. List assumptions separately so they can be checked; wrong assumptions are where designs quietly break.

5. Options considered

For each realistic option: a short description, pros, cons, rough cost and effort, and risks. Include “buy”, “integrate something existing”, and “do nothing” where they are genuine options. (More on that in build vs buy.)

6. Recommended solution

The chosen option and the reasoning. Then the design itself:

• Context diagram: the solution, its users, and the systems around it.
• Components: the main building blocks and what each is responsible for.
• Integrations: every connection to another system, with direction, method, and what happens on failure. (See the API integration checklist.)
• Data: what data is created, where it lives, how it moves, and who owns it.
• Security: authentication, authorisation, and how sensitive data is protected.
• Infrastructure: where it runs, at the level of detail the audience needs.

7. Risks

The main risks, how likely and serious each is, and what reduces them.

8. Decisions

A short log of the key decisions: what was decided, why, and what alternatives were rejected. For bigger decisions, link to a separate decision record.

9. Delivery approach and open questions

How it will be delivered (phases, migration, cutover if relevant) and the questions still unanswered, each with an owner.

Template

Copy this into your own docs tool and delete what you don’t need:

# [Solution name] - Solution Architecture

Status: Draft | In review | Approved
Owner:
Last updated:

## 1. Context and problem

## 2. Scope

In scope:
Out of scope:

## 3. Requirements

### Functional

### Non-functional

## 4. Constraints and assumptions

## 5. Options considered

### Option A:

Pros:
Cons:
Cost/effort:
Risks:

### Option B:

## 6. Recommended solution

Why this option:

### Context diagram

### Components

### Integrations

### Data

### Security

### Infrastructure

## 7. Risks

| Risk | Likelihood | Impact | Mitigation |
| ---- | ---------- | ------ | ---------- |

## 8. Decisions

| Decision | Reason | Alternatives rejected |
| -------- | ------ | --------------------- |

## 9. Delivery approach and open questions

Keep it alive, keep it short

• Write the problem and options sections before the design, not after.
• Prefer diagrams plus short explanations over pages of prose.
• Update the decisions section as things change during delivery, so the document stays true.
• If a section doesn’t apply, delete it rather than filling it with boilerplate.

For recording individual decisions as you go, I built a free decision record tool that produces a clean Markdown record you can paste into the same docs.

If you’re not sure what a solution architect is responsible for in the first place, start with what solution architecture is.