•
•
14 min

test 1

Most Software Architecture Documents fail their Architecture Review Board on the same six things — and almost none of those failures are about the architecture itself. This is the practical playbook for writing a SAD an ARB will actually approve: what to include, what to leave out, the diagrams that earn trust, and how to use AUTOSAD to generate 80% of it from your requirements.

Why most SADs fail at the ARB

After watching dozens of ARB sessions, the rejection patterns are remarkably consistent. Architectures rarely fail because they're wrong. They fail because the document doesn't let the board verify they're right within the 60 minutes everyone has on the calendar.

Here are the six failure modes that account for almost every "go back and revise":

  1. No traceable link to requirements. The board can't tell which user need each component serves.
  2. Quality attributes treated as adjectives. "Scalable, secure, performant" with no scenarios, thresholds, or measurements.
  3. One view doing five jobs. A single boxes-and-lines blob trying to be a context diagram, a deployment diagram, and a sequence diagram at once.
  4. No decision rationale. The architecture is presented as if it fell from the sky. The board wants to see the alternatives you rejected.
  5. Security & compliance bolted on at the end. Identity, authorization, data classification, and regulatory mapping are afterthoughts.
  6. Diagrams that drift. The deployment diagram and the component diagram disagree, and the document contradicts itself by page 12.

Every section below targets one of these failure modes directly.

‍

Automate over 80% of the system design lifecycle with AI

Video Play Icon

Play Video

What an ARB actually evaluates

Before writing the SAD, you have to understand what it has to survive. A typical enterprise ARB runs a multi-gate review process — initiation, solution review, and architecture review — each with its own scoring rubric. Universities and large enterprises publish theirs publicly, and they're more similar than you'd think. The University of Ottawa documents a three-gate model that mirrors what most Fortune 1000 ARBs run today.

1InitiationBusiness case &option analysisOUTPUTDirection & principlesto evaluate2Solution ReviewFit/gap vs. EAprinciples & roadmapOUTPUTApproved approach,trade-offs logged3Architecture ReviewSecurity, standards,operational feasibilityOUTPUTApprove / conditional /rejectWeek 0–1Week 2–3Week 4–6Each gate has its own checklist — the SAD must satisfy all three
Figure 1 — The three gates of a typical enterprise ARB. Your SAD must answer different questions at each gate.

At each gate, board members are explicitly looking for evidence — not opinions. LeanIX's ARB reference lists the standard evaluation dimensions: strategic alignment, compliance & security, cost management, technical feasibility, performance & scalability, interoperability, and documentation quality. Your SAD has to make it easy for someone to tick a box against each.

The 10 sections every ARB-ready SAD must have

The ISO/IEC/IEEE 42010 template is the lingua franca of architecture description. You don't need to follow it verbatim, but every section below maps to a "must" or "should" in 42010 — which means an ARB chair from any large enterprise will recognize the structure.

# Section What it answers Length
1 Identifying information System name, version, authors, reviewers, change log, references. Boring but mandatory. ½ page
2 Architecture overview What the system is, who it's for, the one-paragraph "elevator pitch" of the architecture. 1 page
3 Stakeholders & concerns Who cares about this system and what each stakeholder worries about. Drives the views you'll show. 1 page
4 Business drivers & requirements Goals, use cases, NFRs. Every later decision must trace back here. 2–3 pages
5 Architecture views Context, container, component, deployment, data. Usually C4 or 4+1. This is where most pages go. 6–10 pages
6 Quality attribute scenarios The utility tree. Measurable scenarios for performance, availability, security, modifiability. 2 pages
7 Architecture Decision Records The decisions you made, the alternatives you rejected, and why. ARB members read this section first. 2–4 pages
8 Security & compliance Identity, authorization, data classification, regulatory mapping (PCI/HIPAA/GDPR/SOC2). 1–2 pages
9 Operations & observability RTO/RPO, runbooks, SLOs, telemetry, incident response. 1–2 pages
10 Risks & open issues Known risks with mitigations, items deferred to a later review. Honesty wins points. ½ page
Rule of thumb

Aim for 18–25 pages total. ARB members will read the first three sections, skim views, and read decisions and risks in detail. Anything longer signals you don't know what's important.

Picking views: C4, 4+1, or IEEE 42010?

All three frameworks are about the same idea — different audiences need different views — but for an ARB audience the C4 model wins on clarity and is what most modern enterprises now standardize on. It's four nested levels of zoom: System Context, Container, Component, and Code — only the first three belong in a SAD.

LEVEL 1System ContextUserSystemExtExtThe big picture:your system + users +external dependenciesLEVEL 2ContainerWeb AppAPIWorkerDBApps, services,databases and howthey communicateLEVEL 3ComponentOrders APIControllerServiceRepoPricingInside one container:components and theirresponsibilitiesLEVEL 4Codeclass OrderService { validate(o) { … } price(o) { … } persist(o) { … }}Skip in your SAD.Code is the source oftruth, not the doc.
Figure 2 — The C4 model. Include Levels 1–3 in your SAD. Level 4 belongs in code, not documentation.

A complete C4 view set for the SAD usually means: one Context diagram, one Container diagram, and one Component diagram per significant container. Plus one Deployment diagram (the "C4 supplementary" diagram) for each target environment.

Common mistake

Don't draw a Component diagram for every container. Pick the 2–3 containers whose internals matter for quality attributes the ARB cares about (usually anything handling auth, payments, or PII). Skip the trivial ones.

Quality attributes & the utility tree

This is the section ARBs grade hardest, and it's where most SADs die. A quality attribute is not "the system should be fast." It's a scenario: a source, a stimulus, an environment, an artifact, a response, and a response measure.

The right way to organize them is the SEI's Quality Attribute Utility Tree, a top-down breakdown from utility → attribute → refinement → scenario. Each leaf gets two priorities: how important it is (H/M/L) and how hard it is for the architecture to deliver (H/M/L).

UtilityPerformanceAvailabilitySecurityModifiabilityLatencyRecoveryConfidentialityDeploy timeCheckout p95 < 800msUnder 5k concurrent users,the checkout API responds inunder 800ms p95 latency.(H,H)RTO ≤ 15minRegion failoverrestores read+writein ≤15 minutes.(H,M)PII at rest AES-256All PII columnsencrypted in DBwith KMS rotation.(H,L)New region in 1 dayAdd a deploymentregion with IaC in≤ 1 business day.(M,M)Reading the prioritiesEach leaf is annotated (Importance, Difficulty)on a H/M/L scale. Architects focus first on (H,H) & (H,M) —high stakes and hard to achieve. These drive the analysis in ATAM Step 6.Drives architectureLower stakes / easyAlready solved
Figure 3 — A Quality Attribute Utility Tree. Each scenario is testable. The (H,H) ones drive your architecture decisions.

The six parts of a complete scenario

An ARB-grade scenario must have all six. Drop any one and the scenario is unprovable.

  1. Source — who or what initiates the stimulus (a user, a load test, a region outage)
  2. Stimulus — what happens (5k concurrent requests, AZ goes dark, malformed input)
  3. Environment — under what conditions (normal load, peak, degraded mode)
  4. Artifact — what part of the system is affected (checkout API, primary DB)
  5. Response — how the system reacts (failover, rate-limit, return cached)
  6. Response measure — the number (≤800ms p95, ≤15min RTO, 99.95% monthly)

Defending the SAD: ATAM in 90 minutes

The Architecture Tradeoff Analysis Method (ATAM), developed by the SEI at Carnegie Mellon, is the gold-standard process most ARBs are informally running, whether they call it that or not. Knowing the nine steps means you can predict every question the board will ask before the meeting starts.

PRESENTATIONINVESTIGATIONTESTING & REPORTING1Present the ATAMSet process & expectations2Present business driversWhy are we building this?3Present architectureWalk the views4Identify approachesPatterns & tactics used5Build utility treePrioritized QA scenarios6Analyze approachesFor each (H,H) scenario7Brainstorm scenariosStakeholders add & vote8Analyze (round two)Map new scenarios9Present resultsRisks, trade-offs, sensitivitiesFOUR ARTIFACTS YOU MUST PRODUCERisksDecisions that may cause future problems for a quality attribute.Non-risksGood decisions worth documenting so they don't get questioned next quarter.Sensitivity pointsParameters where a small change shifts a quality attribute substantially.Trade-offsDecisions that improve one QA while degrading another. Name them explicitly.
Figure 4 — The nine ATAM steps and the four artifacts every architect should be able to produce on demand.

If your SAD already documents risks, non-risks, sensitivity points, and trade-offs for each high-priority quality attribute scenario, you've effectively pre-run ATAM. ARB sessions become a confirmation instead of an interrogation.

Non-functional requirements ARBs actually grade

Every ARB I've watched scores NFRs against the same six categories. If your SAD has a one-line table mapping each NFR to a measurable target and the architectural mechanism that delivers it, you've already won 30% of the review.

Category Typical target How the architecture delivers
Availability 99.95% monthly, RTO 15min, RPO 5min Multi-AZ + cross-region replica, health checks, automated failover
Performance p95 <800ms at 5k concurrent users CDN + autoscaling app tier + read replicas + connection pool tuning
Security OWASP ASVS L2, TLS 1.3, AES-256 at rest, MFA for admin WAF, secrets manager, KMS, IAM least-privilege, SSO/OIDC
Scalability 10× user growth without architecture change Stateless services, sharded DB, async queues, horizontal autoscaling
Observability MTTR <30min, full distributed tracing OpenTelemetry, structured logs, SLO dashboards, on-call runbooks
Compliance PCI-DSS / HIPAA / SOC2 / GDPR per applicable data class Tokenization, encryption boundaries, audit log immutability, data residency controls

Architecture Decision Records (ADRs)

The most-skipped, most-valuable section. An ADR captures one decision, the alternatives considered, and the trade-offs accepted. ARB members read ADRs first because they explain why — and that's where credibility lives.

# ADR-007: Use a shared "commerce-db" for Orders, Cart, and Payments ## Status Accepted — 2026-05-12 ## Context We are decomposing the monolith into 7 services. Strict "one DB per service" would create three databases that constantly cross-reference the same order_id, customer_id, and pricing snapshots. Distributed transactions across them would harm both performance and modifiability. ## Decision Orders, Cart, and Payments share a single PostgreSQL instance with separate schemas, owned by the Commerce capability team. Cross-schema foreign keys are forbidden; integration is via service interfaces. ## Alternatives considered 1. Strict DB-per-service + saga pattern — rejected: 3× ops overhead 2. Single shared DB, no schema isolation — rejected: blast radius 3. Shared DB with per-service schemas (chosen) ## Consequences + Single transactional boundary for the checkout flow + Lower ops cost than 3 databases − Coupling at the data layer; team must enforce schema discipline − Migration effort if Commerce ever splits into separate bounded contexts ## Trade-off Modifiability (−) for Performance (+) and Operational simplicity (+). Re-evaluate when Commerce team headcount exceeds 12.
Pattern

Aim for 6–12 ADRs in a typical SAD. One per architecturally significant decision. Number them, link them from the views they affect, and never delete an ADR — supersede it with a new one and link the chain.

The pre-ARB self-review checklist

Run your draft through this before the meeting. If you can't tick all 20 boxes, expect to be sent back.

Pre-ARB self-review checklist
☐Every requirement traces to at least one component or container.
☐Every component traces back to at least one requirement.
☐Each quality attribute has at least one measurable scenario.
☐High-priority (H,H) scenarios have an explicit architectural mechanism documented.
☐You have C4 Levels 1, 2, and 3 for the significant containers.
☐You have a deployment diagram for each target environment.
☐Diagrams and prose agree on component names. No drift.
☐Each ADR names alternatives rejected and the trade-off accepted.
☐Security section names: AuthN method, AuthZ model, data classification, encryption boundaries.
☐Compliance section maps each regulated data flow to its applicable standard.
☐RTO, RPO, SLO targets are stated with numbers.
☐Observability section names the telemetry stack and signal-to-alert mapping.
☐Open risks are explicitly listed with proposed mitigation.
☐Decisions reference EA principles (or explain the deviation).
☐External system dependencies are listed with SLA & failure-mode notes.
☐The document is ≤ 25 pages.
☐An executive summary fits on one page.
☐Cost projection (or at least cost class) is documented.
☐Roadmap to target state is included if the system is being modernized.
☐Authors, reviewers, and approvers are named.

How AUTOSAD automates 80% of this

Writing the document above takes the average architect 4–6 weeks per system. After 30 of these I built AUTOSAD because I was tired of the same week-long copy-paste between requirements docs, Visio, Confluence, and the ARB template. AUTOSAD generates each section directly from your requirements and keeps everything synchronized when those requirements change.

Animation showing a monolith application being split into 7 microservices with three shared databases, generated by AUTOSAD from requirements.
Figure 5 — AUTOSAD generating a decomposition view from requirements, with shared-database couplings explicitly flagged. The same model becomes a section of the SAD.

What AUTOSAD generates per SAD section

SAD section AUTOSAD output
Business drivers & requirements W6H requirements elicitation (Who, What, When, Where, Why, Which, How), use-case models, and use-case specifications generated from stakeholder interviews.
Stakeholders & concerns Stakeholder–concern matrix derived from W6H "Who" + "Why" axes.
C4 Context view (Level 1) Generated automatically from requirements; external systems inferred from integrations named in use cases.
C4 Container view (Level 2) One-click toggle between monolith, microservices, and pub/sub styles — same requirements, three architectures, identical traceability.
C4 Component view (Level 3) Components synthesized from use-case specifications, grouped by bounded context.
Data model Conceptual & logical data models derived from entities named in W6H "What." Shared-DB couplings flagged.
Deployment view AWS, Azure, and GCP deployment diagrams generated from the container view. Multi-cloud variants in one click.
Sequence / interaction diagrams One per major use case, auto-generated and re-rendered when the use case changes.
ADRs Each architectural style toggle (monolith → micro) auto-creates an ADR draft with alternatives considered and trade-offs flagged.
SAD export Full document exported to Word, PDF, or Markdown using your enterprise's template — including all diagrams.
Governance / review Unlimited free reviewers — invite your entire ARB to comment on the live model without per-seat fees.
The synchronization point

The reason most SADs drift between sections is that each view lives in a different tool. In AUTOSAD, requirements, views, ADRs, and the exported document are one model. Change a requirement and every downstream artifact updates. The ARB sees the same single source of truth the architect sees.

A realistic workflow

  1. Day 1. Paste or import the requirements brief. AUTOSAD extracts use cases via W6H and asks clarifying questions.
  2. Day 2. Toggle architectural style (monolith / micro / pub-sub). Pick the one whose ADR draft you can defend.
  3. Day 3. Review generated quality attribute scenarios; add the (H,H) ones the AI missed.
  4. Day 4. Invite ARB reviewers (unlimited, free). They comment in-line; you address.
  5. Day 5. Export the full SAD to Word in your enterprise template. Walk into the ARB.

That's a 5-day path to an ARB-ready document — most of the saved time goes into thinking about the architecture instead of formatting it.

Stop reformatting Word docs. Start defending decisions.

AUTOSAD turns your requirements into an ARB-ready Software Architecture Document — diagrams, ADRs, NFRs, and deployment views included. 30-day free trial, no credit card.

Start free trial → Book a demo
Share this post
Png version of AUTOSAD Logo

Social Media
Privacy Policy
© Copyright 2024 AUTOSAD.  All rights reserved.