reph

Templates · Engineering

ADR template

Architecture decision record: one decision, its context and consequences

Start with this template →Sign in

Opens on reph with the template ready to start. No account needed; sign in to keep your document.

Use it when

You are making one significant, hard-to-reverse technical decision and want the context recorded for whoever inherits it

Who it's for

EngineerTech leadEngineering manager

Part of a kit

Engineering rituals, step 3 of 7. Propose, decide, build and review: RFC, design doc, ADR, spec, PR description and review checklist.

Filled example

The template filled in for a made-up company, so you can see what good looks like.

ADR 014: Use Postgres logical replication for the reporting replica

Status: Accepted · Date: 2026-03-12 · Deciders: Priya Raman, Tomas Okafor

Context

Northwind's reporting dashboards query the primary Postgres cluster directly. Since January, month-end finance exports have pushed primary CPU above 85% for two to three hours, and on 2026-02-28 a long-running export held a lock that delayed checkout writes by up to 9 seconds (incident INC-2207). Finance needs fresh data (under five minutes stale), and the platform team cannot add a second large primary before Q3.

Decision drivers

  • Reporting queries must never block or slow transactional writes
  • Data no more than five minutes stale for finance
  • Must not require downtime on the primary to set up
  • Run by the existing two-person platform team, no new vendor

Considered options

Option Summary
A Postgres logical replication to a dedicated reporting instance
B Nightly ETL into the data warehouse (Snowflake)
C Physical streaming replica with hot_standby_feedback

Decision outcome

Logical replication isolates reporting load completely while staying within minutes of fresh, and the team already runs it for the search index. Chosen: Option A

Consequences

Positive

  • Month-end exports no longer touch the primary, removing the INC-2207 failure mode
  • The reporting instance can carry its own indexes tuned for analytics
  • Replication lag is visible as a metric we already alert on

Negative

  • Schema changes (DDL) are not replicated; every migration now needs a matching step on the replica
  • One more instance to patch and pay for, roughly $640 per month
  • Large backfills on the primary can push replication lag past the five-minute target

Neutral

  • Finance moves its saved queries to a new connection string

Links

  • Design doc: Reporting isolation (Tomas Okafor, 2026-03-02)
  • Incident INC-2207 postmortem
  • Supersedes ADR 009 (read traffic stays on primary)

Review

Review by: 2026-03-11

Reviewer Role Status
Priya Raman Platform tech lead Approved
Dana Whitfield Finance systems Approved
Leo Marchetti SRE Approved with note

Decision record

Decision Date Decided by Notes
Accepted 2026-03-12 Priya Raman Leo asked for a lag alert at 3 minutes before go-live; tracked in PLAT-512

The template

Show the blank template

ADR

Status: Proposed · Date: [date] · Deciders: [your name]

Context

The forces at play (technical, organizational, timeline) that make a decision necessary now. State the problem before the solution.

Decision drivers

  • A constraint or requirement that shapes the options, e.g. "must not require downtime"

Considered options

Option Summary
A
B
C

Decision outcome

Chosen option and the one-sentence reason it wins over the others. Chosen: Option _

Consequences

Positive

What gets easier or better as a direct result of this decision.

Negative

The real costs or new constraints this decision introduces. A consequences section with nothing here isn't credible.

Neutral

Side effects that are neither clearly good nor bad, just true.

Links

  • Related ADRs, the design doc this formalizes, tickets

Review

Who must sign off, and by when. Reviewers record their call in the decision record so the outcome is findable later.

Review by: [date, usually five working days out]

Reviewer Role Status
Pending
Pending

Decision record

Decision Date Decided by Notes
Accepted / Rejected / Needs changes

Questions

How is an ADR different from a design doc?
A design doc explores a change, an ADR records one decision and why, so it stays short and permanent
Can I edit an ADR after it is accepted?
No, write a new ADR that supersedes it and link the two
Who should be a decider?
The people accountable for living with the consequences, usually the tech lead and the owning team

Fill it with your agent

Connect Claude to reph over MCP, then paste this. The draft arrives as suggestions you accept or reject section by section. How to connect Claude.

Find my reph doc "ADR" with search_docs, then read it with read_doc. Draft Context, Decision drivers and Considered options from the linked design doc, related tickets and earlier ADRs I reference, with at least two real negative consequences for the chosen option. File it with suggest_edit, one replace_section op per section (heading line kept) so each can be accepted alone. Ask each open question (any option you could not compare fairly) with add_comment quoting that section's heading line, then call request_review with a one-line summary.

Related templates

RFC (request for comments)

A lightweight proposal circulated for comment before a decision: summary, motivation, proposal, alternatives, drawbacks and open questions, with a comment period and decision record

EngineerTech leadEngineering managerProduct manager

Design doc

Context, goals, proposed design, alternatives and rollout for a technical change

EngineerTech leadEngineering manager

Technical spec

Implementation-level spec: overview, goals, approach, milestones

EngineerTech lead

API spec

Endpoints, request/response shapes, errors, auth and versioning

EngineerTech lead

Pull request description

What changed and why, the linked issue, how to test, screenshots, risk and rollback, and a reviewer checklist

EngineerTech lead

Code review checklist

What to check before approving a change

EngineerTech lead

Start with this template →Sign in