Architecture Decision

Overview

Generate comprehensive Architecture Decision Records (ADRs) in under 90 seconds. Document technical decisions with full context, evaluated options, and implementation consequences for your engineering team.

Use Cases

• Document API migration decisions (REST to GraphQL, monolith to microservices) during sprint planning
• Capture database technology choices (PostgreSQL vs MongoDB) before implementation starts
• Record infrastructure decisions (AWS vs GCP, Kubernetes vs serverless) for future reference
• Track frontend framework selections (React vs Vue, Next.js vs Remix) with team consensus
• Document security architecture choices (OAuth vs JWT, encryption standards) for compliance audits

Benefits

ADRs prevent the “why did we choose this?” conversations six months later. This template ensures you capture:

• Save 2-3 hours per architecture decision - Fill in context and options instead of starting from scratch
• Team alignment in minutes - Stakeholders understand trade-offs without lengthy meetings
• Future-proof documentation - New team members understand historical context without archaeology
• Compliance-ready records - Security and audit teams get full decision rationale on demand

Template

Document architecture decision:

Decision title: {{title}}
Context: {{context}}

Problem:
{{problem}}

Considered options:
{{options}}

Chosen solution: {{solution}}

Include:
- Decision drivers
- Pros and cons of each option
- Consequences
- Implementation notes
- Related decisions

Status: {{status}}

Properties

• title: Single-line Text
• context: Multi-line Text
• problem: Multi-line Text
• options: Multi-line Text
• solution: Multi-line Text
• status: Single Selection (default: Proposed)
  • Options: Proposed, Accepted, Rejected, Superseded, Deprecated

Example Output

Here’s what this template generates when documenting a mobile API architecture decision:

# Architecture Decision Record: Migrate from REST to GraphQL for Mobile API

## Status
Proposed

## Context
Our mobile app currently uses a REST API with 30+ endpoints. Mobile teams report
performance issues due to over-fetching and multiple round trips. Network conditions
in emerging markets make this worse.

## Problem
- Mobile app load times: 3-5 seconds on 3G connections
- Waterfall requests create sequential delays
- 40% onboarding abandonment rate
- Each screen requires 3-5 API calls to fetch related data

## Decision Drivers
- Reduce mobile app load times from 3-5 seconds to under 2 seconds
- Improve onboarding completion rate
- Support users on 3G networks in emerging markets
- Minimize bandwidth usage for mobile clients

## Options Considered

### Option 1: Optimize existing REST endpoints with better caching
Pros: Minimal code changes, familiar technology, lower implementation risk
Cons: Doesn't solve over-fetching, still requires multiple round trips

### Option 2: Migrate to GraphQL with query batching
Pros: Single request per screen, clients request only needed fields, reduces
      bandwidth significantly
Cons: Learning curve, backend refactoring required, complex caching strategy

[Additional options evaluated...]

## Decision
Migrate to GraphQL with phased rollout starting with highest-traffic screens.

## Consequences
Positive: 60-70% reduction in API round trips, load times drop to 1-2 seconds on 3G
Negative: Backend team needs GraphQL training (2-3 weeks), implementation overhead

The full output includes detailed pros/cons for each option, implementation notes, risks with mitigations, and links to related decisions.

Common Mistakes When Writing ADRs

Too vague about the problem - “Performance is bad” doesn’t help future readers. Quantify it: “API response time is 850ms at p95, users on 3G experience 4-second load times.”

Missing the “why now” - ADRs should explain timing. What changed? New requirements? Technical debt reached critical mass? User feedback triggered this?

Listing options without real evaluation - If you didn’t seriously consider an option, don’t include it. Each option needs genuine pros/cons, not strawmen.

Forgetting consequences - Every architecture decision has trade-offs. Document what you’re giving up, not just what you’re gaining. Future you will thank past you.

Skipping implementation notes - High-level decisions need concrete next steps. Include phasing strategy, team assignments, and timeline estimates.

Tips for Better Architecture Decisions

Fill in the context section with measurable metrics wherever possible. “Users report slow performance” becomes “p95 response time is 1.2s, target is 300ms.”

When listing options, include at least one you rejected. This shows you evaluated alternatives and explains why the chosen path is better.

For complex decisions involving multiple teams, run the filled template by stakeholders before finalizing. Catch gaps in reasoning early.

If your decision becomes superseded later, update the status and link to the new ADR. This creates a decision timeline your team can follow.

The template works best when you fill it in during the decision process, not after implementation starts. Capture reasoning while it’s fresh.

Frequently Used Together

Architecture decisions often require supporting documentation. These templates work well alongside ADRs:

• API Documentation - Document the APIs affected by your architecture decision
• Code Review - Review implementation of architecture changes
• Refactoring Plan - Plan the technical work to implement your decision
• Performance Optimization - Track performance improvements from architecture changes

Related Templates

Explore more Coding templates or browse all templates.