Quickstart

Create Your First SAD

This guide walks you through producing a minimal Solution Architecture Document. By the end, you will have a structured SAD covering the essential sections.

What you need

A text editor and a basic understanding of the solution you are documenting. No tools or installations required.

What 'Minimum' means

ADS defines three documentation depths — Minimum, Recommended, and Comprehensive — using the requirement keywords from RFC 2119: SHALL (Minimum: must include), SHOULD (Recommended: should include), MAY (Comprehensive: optional but useful for critical systems).

This Quickstart targets Minimum depth — the right level for early-stage designs, proofs of concept, and dev/test reviews. You’ll fill in only the sections marked Yes in the Minimum column of the Depth Cheat Sheet. Quality Attributes, Lifecycle, and most of the deeper governance sections start at Recommended depth and aren’t required here.

Step 1: Download a Template

Download the Markdown template — or copy it to your clipboard for pasting into Confluence or a wiki.

Step 2: Fill in Document Control

Complete the metadata table at the top:

Field	What to Write
Document Title	A clear name — e.g., “Customer Portal SAD”
Solution Name	The name of the system or application
Author	Your name
Version	0.1
Status	Draft
Classification	Internal (most common starting point)

Step 3: Write the Executive Summary

Answer three questions in a short paragraph:

1. What does the solution do? — 1-2 paragraphs
2. What business problem does it solve? — 1-2 paragraphs
3. What is the high-level approach? — 1-2 paragraphs

Then list what is in scope and out of scope as bullet points.

Before describing the architecture itself, identify who the design serves and who needs to review it.

Step 4: Identify the Stakeholders

List the people whose decisions or concerns the design must address. Even a Minimum SAD needs this — a design with no identified stakeholders has nobody to review it:

Stakeholder	Role	Key Concern
Product Owner	Sponsor	Business outcomes, timeline
Engineering Lead	Builder	Maintainability, team skills fit
Security	Reviewer	Authentication, data protection
SRE / Operations	Operator	Reliability, on-call burden

Three to six stakeholders is normal at Minimum depth. The full Section 2 covers concerns matrices and compliance context — not required here.

Step 5: Describe the Architecture

Complete the five views required at Minimum depth (see the Depth Cheat Sheet for the full rules):

Logical View (Section 3.1) — List the main components:

Component	Type	Technology	Status
Frontend	Web App	React	New
API	API Service	Node.js	New
Database	Database	PostgreSQL	New

Integration & Data Flow View (Section 3.2) — Show how components talk to each other and to anything outside the solution:

From	To	Protocol	Encrypted	Purpose
Frontend	API	HTTPS	Yes	User actions
API	Database	TCP-TLS	Yes	Reads/writes
API	Identity Provider	HTTPS	Yes	SSO

A simple data-flow diagram (Mermaid, draw.io, or hand-drawn) helps too.

Physical View (Section 3.3) — State where it runs:

Field	Value
Hosting	Cloud (AWS / Azure / GCP)
Service Model	PaaS
Region	UK South

Data View (Section 3.4) — List the data stores and how the data is classified:

Data Store	Store Type	Classification
Application database	Relational DB	Internal
Object storage	Object storage	Internal

Security View (Section 3.5) — State how users authenticate and how data is protected:

Field	Value
Authentication	SSO via Entra ID / Okta
Authorisation	Role-based, enforced at the API
Encryption at Rest	Yes (provider-managed keys)
Encryption in Transit	Yes (TLS 1.2+)

Step 6: Capture Key Risks

Add at least one risk to the Decision Making section:

ID	Risk	Severity	Likelihood	Mitigation
R-001	Vendor lock-in to cloud provider	Medium	Medium	Use managed services with open APIs where possible

Done — Here’s What You Built

You now have a structured SAD at Minimum depth. It should look something like the example below. Note the jump from Section 3 (Architectural Views) to Section 6 (Decision Making) — Sections 4 (Quality Attributes) and 5 (Lifecycle) are not required at Minimum depth, so a Minimum SAD skips them entirely.

# Solution Architecture Document — Customer Portal

| Field | Value |
|-------|-------|
| Author | Jane Doe |
| Version | 0.1 |
| Status | Draft |
| Classification | Internal |

## 1. Executive Summary
The Customer Portal is a web application that allows customers
to view their account details and submit support requests.
It replaces a legacy PHP application that is end-of-life.

**In Scope:** Portal frontend, API backend, database.
**Out of Scope:** CRM integration (Phase 2), mobile app.

## 2. Stakeholders
| Stakeholder | Role | Key Concern |
|-------------|------|-------------|
| Product Owner | Sponsor | Customer adoption, timeline |
| Engineering Lead | Builder | Maintainability |
| Security | Reviewer | Authentication, data protection |
| SRE | Operator | Reliability, on-call burden |

## 3.1 Logical View
| Component | Type | Technology | Status |
|-----------|------|-----------|--------|
| Frontend  | Web App | React | New |
| API       | API Service | Node.js | New |
| Database  | Database | PostgreSQL | New |

## 3.2 Integration & Data Flow
| From | To | Protocol | Encrypted |
|------|----|---------|-----------|
| Frontend | API | HTTPS | Yes |
| API | Database | TCP-TLS | Yes |
| API | Okta | HTTPS | Yes |

## 3.3 Physical View
| Hosting | Cloud (AWS) |
| Service Model | PaaS |
| Region | eu-west-2 |

## 3.4 Data View
| Data Store | Type | Classification |
|------------|------|----------------|
| Application DB | Relational DB | Internal |

## 3.5 Security View
| Authentication | SSO via Okta |
| Authorisation | Role-based, enforced at API |
| Encryption at Rest | Yes (AWS KMS) |
| Encryption in Transit | Yes (TLS 1.2+) |

## 6.3 Risks
| ID | Risk | Severity | Mitigation |
|----|------|----------|-----------|
| R-001 | Vendor lock-in | Medium | Use open APIs |

That is a valid Minimum-depth SAD. It covers the sections required for a development or test review.

Minimum vs full standard

The quickstart covers only the Minimum sections — enough for early-stage designs and dev/test reviews. The full standard has more sections for production-ready and enterprise-grade documentation (quality attributes, lifecycle, scenarios, etc.). Use the Depth Cheat Sheet to see exactly what’s required at each level — you only fill in what your project needs.

What Next?

• See what’s needed for your depth — check the Depth Cheat Sheet for a single-page view of what to fill in
• See a completed example — review the Employee Directory example to see what a full Recommended-depth SAD looks like
• Expand to Recommended depth — add quality attributes (Section 4), lifecycle (Section 5), and scenarios (Section 3.6) before production approval
• Score your design before review — use the 0–5 Compliance Scoring rubric to self-assess each section’s maturity. Reviewers expect this on Recommended and Comprehensive submissions
• Use AI assistance — import a template into ChatGPT, Claude, or Copilot along with your project brief to generate a more detailed first draft

Time to production?

A Minimum SAD takes around 15–30 minutes if you already understand the solution. A Recommended SAD (production-ready) typically takes 1–2 hours for a single architect, longer for collaborative drafts. A Comprehensive SAD for a critical or regulated system takes 1–2 days including threat modelling and capacity planning. The documentation depth levels ensure you invest time proportional to the solution’s criticality.