Overview

The Architecture Description Standard (ADS) defines how to write a Solution Architecture Document (SAD) — the single document that describes how a technology solution is designed, built, and operated.

Purpose

This standard defines the required structure and content for Solution Architecture Documents (SADs). The architectural views and quality attributes within a SAD constitute the High Level Design (HLD) of the solution.

A Solution Architecture Document conforming to this standard serves the following functions:

1. Communication — Provides a shared understanding of the solution architecture across all stakeholders
2. Governance — Enables the architecture governance process to evaluate the design against quality criteria
3. Traceability — Establishes links between design decisions, business requirements, quality attributes, and applicable standards
4. Reference — Acts as a living document that accurately describes the current-state architecture
5. Evidence — Demonstrates that the solution is well-architected against industry-recognised frameworks

Scope

This standard applies to the documentation of any technology solution architecture, regardless of:

• Deployment model — cloud-native, on-premises, hybrid, multi-cloud, or SaaS
• Scale — from single applications to multi-application ecosystems
• Industry — the standard is organisation-agnostic and sector-neutral
• Lifecycle stage — new builds, migrations, modernisations, or incremental changes

The standard is extensible — organisations can add custom sections, map to internal tools and standards, and define governance gates without modifying the core structure. See Adopting ADS for a rollout guide.

Audience

This standard is intended for use by:

Role	Primary Sections
Solution Architects	All sections — primary authors of SADs
Enterprise Architects	Framework Alignment, Quality Attributes, Governance
Security Architects	Section 3.5 (Security View), Quality Attributes
Infrastructure Engineers	Section 3.3 (Physical View), Quality Attributes
Development Leads	Section 3.1 (Logical View), Section 5 (Lifecycle)
Architecture Governance	All sections — as a review and governance framework (e.g., ARB, design authority)

Document Structure

A Solution Architecture Document conforming to ADS is organised into three tiers:

Tier 1 — Architectural Views (Sections 3.1 – 3.6)

The architecture is described through complementary views, each addressing different stakeholder perspectives. These are based on Kruchten’s 4+1 Architectural View Model — a widely-used framework that organises architecture documentation into Logical, Process, Development, and Physical views, plus Scenarios that tie them together — extended here with dedicated Data and Security views.

Together, these views form the High Level Design (HLD) of the solution:

View	Viewpoint	Primary Stakeholders
3.1 Logical View	Application architecture, components, patterns	Architects, Developers
3.2 Integration & Data Flow View	Data flows, integrations, interfaces	Integrators, Architects
3.3 Physical View	Deployment, hosting, networking, environments	Infrastructure, DevOps
3.4 Data View	Data stores, classification, privacy, lifecycle	Data Architects, Compliance
3.5 Security View	IAM, encryption, monitoring, threat model	Security, CISO, Compliance
3.6 Scenarios	Key use cases, architecture decision records	All Stakeholders

No single view provides a complete description of the architecture. Together, the views provide a holistic picture addressable by all stakeholder concerns.

Tier 2 — Quality Attributes (cross-cutting)

Evaluate the cross-cutting quality attributes across all architectural views. These are derived from the cloud Well-Architected Frameworks:

Quality Attribute	Focus
4.1 Operational Excellence	Observability, monitoring, operational procedures
4.2 Reliability & Resilience	DR, scalability, fault tolerance, backup and recovery
4.3 Performance Efficiency	Performance requirements, resource optimisation
4.4 Cost Optimisation	Cost analysis, FinOps practices
4.5 Sustainability	Energy efficiency, carbon impact, resource efficiency

Tier 3 — Lifecycle & Governance

Lifecycle Management (Section 5)

Describes how the solution is developed, deployed, operated, and eventually retired — including CI/CD, migration strategy, resourcing, release management, and exit planning.

Decision Making & Governance (Section 6)

Captures the constraints, assumptions, risks, dependencies, and issues that shaped the design. Documents key architecture decisions (ADRs), guardrail exceptions, and compliance traceability.

How the Sections Relate

Reading order: A completed SAD tells a story. It begins with the business context and who cares about the solution (Sections 0-2). It then describes the architecture itself through multiple views (Section 3). It evaluates how well the architecture performs against quality attributes (Section 4). It explains how the solution is built, deployed, and operated (Section 5). Finally, it records the decisions, risks, and governance that shaped the design (Section 6).

The diagram below shows how the three tiers work together. Architectural views describe what the solution is. Quality attributes assess how well it performs. Lifecycle and governance cover how it is built, run, and governed.

Documentation Depths

This standard assigns each section a documentation depth — Minimum (SHALL), Recommended (SHOULD), or Comprehensive (MAY) — that defines when it must be completed. This enables progressive adoption: begin with Minimum for early-stage designs, expand to Comprehensive for critical and regulated systems.

See Conformance and Usage for the full depth table, terminology definitions, and governance gate mapping.

Conformance

A Solution Architecture Document conforms to this standard when:

1. All sections marked Minimum are completed
2. The document structure follows the section numbering and hierarchy defined herein
3. Architectural views address the stakeholder concerns identified in Section 2
4. Quality attributes are evaluated as cross-cutting lenses across the architectural views
5. The document is validated against the JSON Schema (ADS Schema v1.0.0) if machine-readable output is required

A document that additionally completes all Recommended sections achieves full conformance.

---

Why ADS?

Architecture documentation is inconsistent across the industry. Teams use a patchwork of templates — some too abstract to guide real work, others too platform-specific to generalise. After analysing widely-used frameworks and real-world architecture documents, gaps appear in every single one.

What’s Missing from Existing Frameworks

Documentation Depth Levels

No existing template provides guidance on how much detail is needed for different project scales. ADS defines three tiers (Minimum, Recommended, Comprehensive) with RFC 2119 keywords (SHALL / SHOULD / MAY) so teams right-size their effort.

Machine-Readable Schema

Every template reviewed is prose-only. ADS provides a JSON Schema with atomic, enumerated fields — enabling automated completeness checks, cross-SAD comparison, and multi-format generation (Markdown, Word, web).

Dedicated Security View

Most frameworks have no dedicated Security View. Security is either buried in cross-cutting concepts, treated as a quality pillar, or absent entirely. ADS treats security as a first-class architectural view (Section 3.5).

Dedicated Data View

Most frameworks lack a structured Data View. Data architecture is scattered across other views or missing. ADS provides a dedicated Data View (Section 3.4) covering data models, flows, classification, retention, and sovereignty.

Cloud WAF-Aligned Quality Attributes

No existing documentation template aligns quality attributes to the cloud Well-Architected Frameworks. ADS maps cross-cutting quality attributes (Section 4) to AWS, Azure, GCP, Oracle, and IBM.

Feature Comparison

How ADS compares against the most widely-used frameworks:

Feature	ADS	arc42	bflorat	ALMBoK	NHS SAF
Architectural views (4+1 aligned)	6 views	4 views	5 views	13 views	Guidance only
Dedicated Security View	✅	❌	✅	✅	Guidance only
Dedicated Data View	✅	❌	❌	✅	Guidance only
Integration & Data Flow View	✅	Partial	❌	✅	Guidance only
Cloud WAF quality attributes	✅ 5 providers	❌	❌	❌	References only
Documentation depth levels	✅ 3 tiers	❌	❌	❌	Informal
RFC 2119 keywords	✅	❌	❌	❌	❌
JSON Schema / validation	✅	❌	❌	❌	❌
Atomic enumerated fields	✅	❌	❌	❌	❌
Lifecycle management	✅	❌	❌	✅	❌
Decision making & governance	✅	Partial	❌	❌	✅
Downloadable templates	✅ MD/YAML/JSON/DOCX	❌	✅ AsciiDoc	❌	❌
Platform-agnostic	✅	✅	✅	✅	NHS-specific
Open-source / free	✅	✅	✅	Partial	✅

See the Framework Alignment page for detailed mappings to ISO 42010, TOGAF, and the cloud Well-Architected Frameworks.

Who Benefits

Solution Architects

A structured, fill-in template that removes the blank-page problem. Atomic fields mean less ambiguity. Depth levels mean you write only what’s needed for your project’s scale.

Architecture Governance

A consistent standard to review SADs against. Machine-readable schema enables automated completeness checks across a portfolio of architecture descriptions.

Delivery Teams

Clear, structured architecture documentation that’s navigable by role — infrastructure engineers read the Physical View, security teams read the Security View.

Organisations

Comparable architecture descriptions across projects. Portfolio-level analysis of quality attributes, risk posture, and compliance coverage.

---

Ready to Start?

• Quickstart — create your first SAD in minutes
• Depth Cheat Sheet — see exactly what to fill in at each depth
• Download a template — Word, Markdown, YAML, or JSON
• See completed examples — four worked examples across different project types

Contributing

ADS is open-source and hosted on GitHub. Contributions are welcome — submit issues, suggest improvements, or open a pull request. The standard content is licensed under CC BY 4.0 and the source code under MIT.