Templates for architects

The documents architects write again and again, ready to copy. Each template keeps the parts that matter and leaves out ceremony. Use the Copy button on any block, paste it into your repository or wiki, and delete the sections a small decision doesn't need. The case studies and modules on this site use the same formats.

Architecture decision record (ADR)

For any decision that is expensive to reverse or crosses teams. One page; superseded, never edited. How to write one is in Module 27.

# ADR-NNN: <the decision, phrased as a statement>

Status: Proposed | Accepted | Superseded by ADR-NNN | Rejected
Date: YYYY-MM-DD
Deciders: <the one person who decides, and who was consulted>
Revisit: <a date, or the signal that would reopen it>

## Context
<The problem and why it needs deciding now. The forces at play: constraints,
the architecture characteristics that matter most (Module 04), numbers that
shape the choice (load, data size, budget, deadline).>

## Decision drivers
- <driver 1, e.g. "p99 under 200 ms at 5,000 writes/s">
- <driver 2, e.g. "Indian customers' data stays in India">

## Options considered
1. <option A>: <one line on how it would work>
2. <option B>: ...
3. <option C>: ...
(Scorecard: <link to the weighted evaluation, if one was done>)

## Decision
We will <do X>, because <the justification against the drivers>.

## Consequences
Good:
- <what becomes easier>
Bad:
- <what becomes harder, costs more, or is now locked in>

## Compliance
<How we will know this decision is still followed: a fitness function,
a review checklist item, a dashboard (Module 26).>

## Dissent and advice
- <who advised or objected, the point they made, and how it was handled>

## Links
- <RFC / design doc, spike results, related ADRs>

Based on Michael Nygard's original format (context, decision, consequences) with the drivers and considered options of MADR, plus compliance, dissent and a revisit date.

Weighted evaluation matrix (scorecard)

For comparing three or four options against the same criteria before writing the ADR. Weight what matters for this decision, score each option from 1 to 5, and read the result as a prompt for discussion, not a verdict: if a small change in one weight flips the winner, that criterion is where the real debate is (Module 06). Apply must-haves (a law, a hard latency limit) first, as knockouts: an option that fails one is out, however well it scores elsewhere.

Example: the orders database for a SaaS product with customers in the US and India, where Indian customers' data must stay in India. Change the weights or scores; the Markdown below updates to match.

Architecture review checklist

Ten points for anyone bringing a design to a review or an architecture advisory forum (Module 27). A missing answer isn't a failure; an unknown one is a risk to record.

1. Problem and goals. The problem, who has it, goals and non-goals, and how success is measured.
2. Characteristics. The top three architecture characteristics, each with a measurable target or quality attribute scenario.
3. Options and decision. At least two alternatives with their trade-offs; the significant decisions drafted as ADRs.
4. Data. Who owns each piece of data, how others read it, consistency needs, retention and deletion.
5. Security and compliance. A threat model of the trust boundaries, personal data handled, the regulations that apply and where data must live.
6. Scale. Expected load now and in two years, the first bottleneck, and what happens at 10x.
7. Reliability and recovery. SLOs, failure modes of each dependency, RTO and RPO, and whether the backup restore has been tested.
8. Observability. The SLIs and alerts, tracing across services, and a runbook owner.
9. Cost. A monthly projection now and at 10x, the unit cost, and the largest cost driver.
10. Rollout and rollback. Migration steps, feature flags or traffic shifting, and how to undo it without data loss.

# Architecture review checklist: <system / RFC-NNN>

- [ ] **Problem and goals**: The problem, who has it, goals and non-goals, and how success is measured.
- [ ] **Characteristics**: The top three architecture characteristics, each with a measurable target or quality attribute scenario.
- [ ] **Options and decision**: At least two alternatives with their trade-offs; the significant decisions drafted as ADRs.
- [ ] **Data**: Who owns each piece of data, how others read it, consistency needs, retention and deletion.
- [ ] **Security and compliance**: A threat model of the trust boundaries, personal data handled, the regulations that apply and where data must live.
- [ ] **Scale**: Expected load now and in two years, the first bottleneck, and what happens at 10x.
- [ ] **Reliability and recovery**: SLOs, failure modes of each dependency, RTO and RPO, and whether the backup restore has been tested.
- [ ] **Observability**: The SLIs and alerts, tracing across services, and a runbook owner.
- [ ] **Cost**: A monthly projection now and at 10x, the unit cost, and the largest cost driver.
- [ ] **Rollout and rollback**: Migration steps, feature flags or traffic shifting, and how to undo it without data loss.

Reviewer notes:
- 

RFC or design doc

For a proposal that needs other people's input before it's decided. Comments close on a date, a named person decides, and the decision becomes an ADR (Module 33b).

# RFC-NNN: <title>

Author: <name>          Status: Draft | In review (comments close YYYY-MM-DD) | Accepted | Rejected
Decider: <name>         Reviewers: <teams and people who must be consulted>

## Context and scope
<The landscape and what is being built. Facts, not requirements. Link details.>

## Goals and non-goals
Goals:
- <measurable goal>
Non-goals:
- <something it could reasonably do, but deliberately won't>

## The design
<Overview first, then the parts the trade-offs depend on: a diagram (C4 container
level is usually right), APIs, data model and ownership, how it fails.>

## Alternatives considered
- <alternative>: <why it would work, and the trade-off that ruled it out>

## Cross-cutting concerns
- Security and privacy: <threat model summary, personal data, data residency>
- Reliability: <SLOs, failure modes, RTO and RPO>
- Observability: <SLIs, dashboards, alerts, tracing>
- Cost: <projection now and at 10x; unit cost>
- Rollout: <migration steps, feature flags, how to roll back>

## Open questions
- <question> (owner, needed by)

Disaster recovery plan

For each service: how long it may be down (RTO, recovery time objective) and how much data may be lost (RPO, recovery point objective), and the strategy that meets both. The AWS disaster recovery whitepaper names four strategies, from cheapest to fastest:

# Disaster recovery plan: <system>

## Service tiers
| Service | Tier | RTO (max downtime) | RPO (max data loss) | Strategy |
|---|---|---|---|---|
| Payments API | 1 | 15 min | 0 to 1 min | Warm standby in second region |
| Order history | 2 | 4 h | 15 min | Pilot light |
| Reporting | 3 | 24 h | 24 h | Backup and restore |

## Disasters planned for
- <loss of one zone> -> <what happens automatically>
- <loss of a region> -> <failover steps, who decides>
- <data corruption or deletion> -> <point-in-time restore, how far back>
- <loss of a third-party dependency> -> <degraded mode>

## Failover runbook
1. <who declares the disaster, and how>
2. <steps, with the command or console path for each>
3. <how traffic is moved (DNS, global load balancer), expected time>
4. <how to fail back afterwards>

## Data protection
- Backups: <what, how often, where, encrypted with which key, retention>
- Replication: <synchronous or asynchronous, lag alert threshold>
- Restore test: <last tested YYYY-MM-DD, time it took, result>

## Exercises
- <game day schedule; last exercise and what it found>

Strategies from Disaster Recovery of Workloads on AWS; the same four apply on any cloud. Replication mechanics are in the System design track's replication module.

Technical debt register entry

One per significant debt item, written so a product manager can weigh it against features (Module 29a).

# Debt item: <short name>

Where: <component / files>          Owner: <team>
Quadrant: deliberate | inadvertent, prudent | reckless (Fowler)
Found by: <hotspot analysis, incident, review>

## Interest we pay now
<The recurring cost, in the business's terms: "each checkout change takes
3x longer", "2 incidents a quarter", "onboarding takes 2 weeks longer".>
Estimate: <hours a month, incidents a quarter, or lead time>

## Principal
<What fixing it involves, and an estimate.>

## Options
- Pay down now: <cost, and what it frees>
- Pay down gradually: <boy-scout rule, budget per sprint>
- Accept: <why that's acceptable, and the review date>

## Decision and review date

Cost projection

For the design doc's cost section: drivers per user, unit prices, and the projection at launch, 10x and 100x (Module 22a).

# Cost projection: <system>

Assumptions per monthly active user: <requests>, <GB stored>, <GB sent out>
Unit prices: <region, list prices, date checked>

| Monthly cost             | Launch | 10x | 100x |
|--------------------------|--------|-----|------|
| Users                    |        |     |      |
| Compute                  |        |     |      |
| Database                 |        |     |      |
| Storage                  |        |     |      |
| Data transfer out        |        |     |      |
| Observability            |        |     |      |
| Support, licences        |        |     |      |
| People to operate (FTE)  |        |     |      |
| Total                    |        |     |      |
| Unit cost (per user / per order) |  |     |      |

Largest driver at 100x: <...>, and the design change that would cut it: <...>
Step changes expected: <database tier upgrade at N users, second region, ...>