Decision Guides

Short guides for questions that come up again and again.

Which Documentation Depth do I need?

flowchart TD
  Start[Starting a new SAD] --> Q1{Does the solution
handle customer data,
financial transactions,
or clinical data?}
  Q1 -->|Yes| Q2{Tier 1 Critical
or Tier 2 High?}
  Q1 -->|No| Q3{Does it support
business-critical
operations or have
regulatory scrutiny?}
  Q2 -->|Yes| Comp[Comprehensive]
  Q3 -->|Yes| Rec[Recommended]
  Q3 -->|No| Q4{Is this a PoC,
dev tool, or
internal-only
low-impact app?}
  Q4 -->|Yes| Min[Minimum]
  Q4 -->|No| Rec
  Comp --> Note1[See the Depth Cheat Sheet
for what to fill in]
  Rec --> Note1
  Min --> Note1

Rule of thumb: Documentation depth should match Business Criticality tier.

Tier 1 / 2 → Comprehensive
Tier 3 / 4 → Recommended
Tier 5 → Minimum

Over-document a simple tool and authors resent the process. Under-document a critical system and the business takes on hidden risk.

Do I need a threat model?

flowchart TD
  Start[Considering a threat model?] --> Q1{Customer-facing,
internet-exposed,
or regulated?}
  Q1 -->|Yes| Need[Threat model required
STRIDE or equivalent]
  Q1 -->|No| Q2{Handles personal,
financial, or
clinical data?}
  Q2 -->|Yes| Need
  Q2 -->|No| Q3{New technology
or new integration
pattern for the org?}
  Q3 -->|Yes| Light[Lightweight threat model
recommended]
  Q3 -->|No| Skip[Threat model optional
— describe key controls]
  Need --> Note1[Cover at Comprehensive depth:
threats, attack vectors,
mitigations, residual risk]
  Light --> Note2[Cover at Recommended depth:
top 5 threats, mitigations]

Frameworks to consider: STRIDE (standard), PASTA (attacker-focused), LINDDUN (privacy-focused for GDPR / US HIPAA contexts), OWASP Threat Dragon (tooling).

Split into one SAD or many?

flowchart TD
  Start[Considering one SAD or many?] --> Q1{Is this one
cohesive solution
with one owner?}
  Q1 -->|Yes| One[One SAD]
  Q1 -->|No| Q2{Are the parts
deployed and
operated
independently?}
  Q2 -->|Yes| Multi[Multiple SADs
one per bounded context]
  Q2 -->|No| Q3{Does one part
have different
criticality or
regulatory regime?}
  Q3 -->|Yes| Multi
  Q3 -->|No| One
  One --> Note1[Single document covers
the whole solution]
  Multi --> Note2[Each SAD references siblings
via Dependencies 6.4
and Integration View 3.2]

Good split points:

Different teams own the parts
Different deployment cadence
Different criticality tier
Different regulatory regime (regulated core vs unregulated periphery)

Poor split points:

Splitting “frontend” and “backend” of one application — they deploy together, they’re one solution
Splitting along team boundaries that will change — design by the architecture, not the org chart

When is an ADR warranted?

flowchart TD
  Start[Made an architecture decision?] --> Q1{Would reversing
this decision later
cost more than
one sprint?}
  Q1 -->|Yes| Adr[Write an ADR]
  Q1 -->|No| Q2{Does it cross
team boundaries
or introduce new
technology?}
  Q2 -->|Yes| Adr
  Q2 -->|No| Q3{Did we consider
viable alternatives?}
  Q3 -->|Yes| Adr
  Q3 -->|No| Skip[Not an ADR
— just a choice]
  Adr --> Note1[Document: context,
decision, alternatives,
consequences, affected
quality attributes]

Good ADR candidates: Database choice, authentication model, deployment topology, API style (REST vs GraphQL vs gRPC), cloud provider, major third-party service.

Not ADRs: Library versions, code formatting, naming conventions, day-to-day tactical choices.

Should I list this as a risk, assumption, issue, or constraint?

flowchart TD
  Start[Have a concern to capture?] --> Q1{Has it
already
happened?}
  Q1 -->|Yes| Issue[Issue
Section 6.5]
  Q1 -->|No| Q2{Is it
something we
must work
within?}
  Q2 -->|Yes| Con[Constraint
Section 6.1]
  Q2 -->|No| Q3{Is it
something we're
treating as true
without proof?}
  Q3 -->|Yes| Ass[Assumption
Section 6.2]
  Q3 -->|No| Q4{Does success
depend on
another party
or team?}
  Q4 -->|Yes| Dep[Dependency
Section 6.4]
  Q4 -->|No| Risk[Risk
Section 6.3]

Quick definitions:

Constraint — an unchangeable boundary (budget, regulation, deadline, existing tech)
Assumption — something we’re treating as true but haven’t verified
Risk — something that might happen and would hurt us
Dependency — we need something from outside our control
Issue — something that’s already happened that we need to deal with

Do I need to update an existing SAD, or write a new one?

flowchart TD
  Start[Making a change?] --> Q1{Is the solution
fundamentally
different?}
  Q1 -->|Yes| New[Write a new SAD]
  Q1 -->|No| Q2{Does it change
Tier, regulatory
regime, or
hosting venue?}
  Q2 -->|Yes| New
  Q2 -->|No| Q3{Does it touch
multiple views
or affect
quality attributes?}
  Q3 -->|Yes| Major[Major update
version 2.0]
  Q3 -->|No| Q4{Is it a small
fix or clarification?}
  Q4 -->|Yes| Patch[Patch
version 1.x.y]
  Q4 -->|No| Minor[Minor update
version 1.x]

Update the SAD’s document metadata (version and change history in Section 0) every time. A current SAD is a living document, not a one-time artefact.