Architecture Decisions

ADR Format

The standard Markdown structure for an Architecture Decision Record.

ADR Template

A copy-paste starter file so authors spend time on content, not formatting.

Superseding a Decision

The correct way to change an accepted architectural decision without destroying history.

ADR Review Process

A lightweight gate so ADRs get genuine technical scrutiny, not just rubber-stamp approval.

Context & Impact Mapping

Map which parts of the system a decision touches before committing, so consequences are visible.

ADR Tooling

Tooling to generate, lint, and index ADRs so they stay consistent as the set grows past 20.

Linking ADRs to Code

Bi-directional links between the decision record and the code that implements it.

ADR Anti-Patterns

Common ways ADRs go wrong and how to spot them in review.

PRD Structure

The canonical sections every Product Requirements Document should contain.

User Story Format

The 'As a X, I want Y, so that Z' format and when to use it vs. job-stories.

Acceptance Criteria

The precise, testable conditions that define 'done' for a user story.

Non-Functional Requirements

The performance, security, and reliability targets that are invisible until they're missed.

PRD Review Checklist

A pre-build checklist that catches under-specified PRDs before engineering wastes a sprint.

Stakeholder Alignment

Getting explicit sign-off from every party that will be affected by the feature.

PRD Versioning

How to handle PRD changes after build starts without silently mutating the spec.

PRD vs RFC

When to write a Product Requirements Doc vs an engineering Request for Comments.

Cloud Cost Model

A spreadsheet or script that maps your architecture to a monthly dollar figure before you build it.

Total Cost of Ownership

Include ops, on-call, and migration cost — not just the cloud invoice — when comparing options.

Cost Per Request

The unit economics metric that tells you if the architecture scales financially, not just technically.

Reserved Capacity

Commit to capacity you'll use for 1+ years to cut 30-70% off the compute bill.

Cost Optimization

The ongoing practice of finding and killing waste without degrading performance.

FinOps Practice

The organizational practice of making cloud cost everyone's responsibility, not just finance's.

Cost Attribution

Tagging strategy so every dollar of cloud spend maps to a team, product, and environment.

Spot & Preemptible

Use 60-90% discounted spare capacity for workloads that tolerate interruption.

Capacity Planning

Size every component for the peak load you expect, with headroom, before you build it.

Data Modeling

Choose the storage model and schema that make your access patterns fast and your future changes cheap.

API Design

The contract between your service and its consumers — design it for stability, clarity, and evolution.

Caching Strategy

Decide what to cache, where, and how to invalidate — the three questions that determine if cache helps or hurts.

Scaling Patterns

The architectural shapes that let a system grow — vertical, horizontal, sharding, partitioning — and when each applies.

Consistency Trade-offs

The CAP/PACELC choice between strong and eventual consistency, and how to pick per data type.

Idempotency Design

Make retries safe so the system can self-heal without creating duplicates.

Backpressure

Signal upstream to slow down instead of queuing unboundedly or dropping requests.

Build vs Buy

Decide whether to build a capability in-house or use a managed service / SaaS, based on total cost and strategic value.

Managed vs Self-Hosted

Choose between a cloud-managed service and self-hosting the open-source equivalent, based on ops capacity and cost.

Language Selection

Pick the programming language based on the problem shape, team expertise, and ecosystem — not fashion.

Database Selection

Match the database to the workload — OLTP, OLAP, KV, time-series, search — not to 'the one we know'.

Framework Selection

Pick the framework that's boring and well-documented over the one that's novel and clever.

Vendor Lock-in

Assess and minimize the cost of leaving a vendor, without refusing to use vendors at all.

Observability Tooling

Pick the metrics/tracing/logging stack that lets you debug production in minutes, not hours.

Deployment Platform

Choose where code runs — VMs, containers, functions, or PaaS — based on the workload shape and team capacity.

Decision Triggers

Know the events that should trigger an architecture decision vs. just a task.

Decision Roles

Assign who writes, who reviews, and who decides — so decisions don't stall and aren't unilateral.

Reversibility

Rate each decision by how expensive it is to reverse, and spend effort proportional to that cost.

Decision Criteria

Define the dimensions you'll evaluate alternatives on, before you look at the alternatives.

Alternatives Analysis

Always consider at least 2 alternatives — the first idea is rarely the best, and 'no alternatives' is a red flag.

Decision Documentation

Write the ADR so a future engineer (or you in 6 months) can understand not just what was decided, but why.

Decision Review

Review past decisions periodically to catch ones that are outdated, and to learn from ones that aged well or poorly.