Architecture Decision Records

ADR Template

Every ADR follows this structure:

ADR-NNN: Title of the Decision

Status

[Proposed | Accepted | Deprecated | Superseded by ADR-NNN]

Context

What is the issue that we are seeing that motivates this decision or change? Describe the forces at play (technical, political, social, project-related). Include any constraints, requirements, or assumptions.

Decision

What is the change that we are proposing and/or doing? State the decision in full sentences using active voice. Be specific about what will be done.

Consequences

What becomes easier or more difficult because of this decision? List both positive and negative consequences. Include any follow-up actions required.

When to Write an ADR

Write an ADR for any decision that meets one or more of these criteria:

Trigger Example

Adopting or replacing a technology Switching from REST to GraphQL

Changing an architectural pattern Moving from monolith to microservices

Infrastructure decisions Choosing a cloud provider or database

API design choices Choosing pagination strategy

Authentication/authorization strategy Adopting OAuth2 with PKCE

Data model decisions Choosing between SQL and NoSQL

Cross-cutting concerns Standardizing error handling or logging

Process or convention changes Adopting conventional commits

Build/deployment decisions Choosing CI/CD platform

Decisions that are hard to reverse Anything with significant migration cost

Do NOT Write an ADR For

• Routine implementation choices with low impact

• Temporary decisions that will be revisited within days

• Individual code-level decisions that are covered by style guides

• Choices that are trivially reversible

Status Lifecycle

Proposed --> Accepted --> Deprecated --> Superseded by ADR-NNN

Status Meaning

Proposed Under discussion, not yet decided

Accepted Decision has been agreed upon and should be followed

Deprecated No longer relevant due to changes in the project or environment

Superseded by ADR-NNN Replaced by a newer decision; link to the replacement

Rules

• An ADR is immutable once accepted; never edit the original text

• To change a decision, write a new ADR that supersedes the old one

• Update the old ADR's status to "Superseded by ADR-NNN"

• Keep deprecated and superseded ADRs in the repository for history

Evaluating Alternatives

Use a structured comparison for every ADR with multiple options.

Pros/Cons Matrix

Option A: PostgreSQL

Pros:

• Mature, well-understood RDBMS
• Strong ACID guarantees
• Excellent tooling ecosystem

Cons:

• Horizontal scaling requires additional tooling
• Schema migrations needed for changes

Option B: MongoDB

Pros:

• Flexible schema for evolving data models
• Built-in horizontal scaling (sharding)

Cons:

• Weaker transaction support (multi-document)
• Team has limited operational experience

Weighted Criteria Matrix

For complex decisions, score each option against weighted criteria:

Calculation: sum of (weight x score) for each option.

File Naming and Storage

Conventions

Convention Rule Example

Numbering Zero-padded 4-digit sequential 0001 , 0002 , 0015

File name NNNN-title-slug.md

0003-use-postgresql.md

Storage location docs/adr/ at the repository root docs/adr/0003-use-postgresql.md

Title format ADR-NNN: Imperative sentence ADR-003: Use PostgreSQL for storage

Directory Structure

project-root/ docs/ adr/ 0001-record-architecture-decisions.md 0002-use-typescript-for-backend.md 0003-use-postgresql-for-primary-storage.md 0004-adopt-rest-api-style.md 0005-use-jwt-for-authentication.md README.md (optional index)

Linking ADRs to Code and Issues

• Reference the ADR in code comments near the affected area: // See ADR-003: Use PostgreSQL for primary storage // docs/adr/0003-use-postgresql.md const db = new Pool({ connectionString: DATABASE_URL });

• Link to the relevant issue or PR in the ADR footer:

References

• GitHub Issue: #142
• Pull Request: #158
• Related: ADR-002

Example ADR 1: Choosing a Primary Database

ADR-003: Use PostgreSQL for Primary Storage

Status

Accepted

Context

Our application needs a primary data store for user accounts, orders, and product inventory. We expect the following requirements:

• Strong consistency for financial transactions
• Complex queries across related entities (joins)
• Team has 5 years of collective PostgreSQL experience
• Expected scale: 10M rows in the largest table within 2 years
• Read-heavy workload with occasional write bursts

We evaluated three options: PostgreSQL, MongoDB, and DynamoDB.

Decision

We will use PostgreSQL 16 as our primary database.

We will manage schema changes with a migration tool (golang-migrate) and enforce that all schema changes go through reviewed migration files.

We will use connection pooling via PgBouncer for production deployments.

Consequences

Positive:

• Team can be productive immediately with existing expertise
• ACID transactions simplify order and payment logic
• Rich query capabilities reduce application-level data manipulation
• Large ecosystem of monitoring and backup tools

Negative:

• Horizontal write scaling will require sharding or read replicas if we exceed expected growth significantly
• Schema migrations add friction to data model changes
• We need to manage connection pooling and tuning ourselves

Follow-up actions:

• Set up PgBouncer in the infrastructure configuration
• Create a migration workflow and document in the developer guide
• Establish backup and point-in-time recovery procedures

Example ADR 2: API Style

ADR-004: Adopt REST for Public API

Status

Accepted

Context

We are building a public API for third-party integrations. The API will be consumed by partners with varying levels of technical sophistication. We need to choose between REST, GraphQL, and gRPC.

Key factors:

• Partners expect a well-documented, stable API
• Most consumers are web applications and mobile clients
• We want to minimize onboarding friction for partners
• Internal services also need to communicate, but that is a separate concern (see future ADR for internal RPC)

Decision

We will adopt RESTful API design for our public-facing API.

Conventions:

• JSON request and response bodies
• Plural resource nouns in URL paths (e.g., /api/v1/orders)
• Cursor-based pagination for list endpoints
• Versioning via URL path prefix (/api/v1/, /api/v2/)
• Standard HTTP status codes per our api-design skill

We will use OpenAPI 3.1 for specification and generate documentation from it.

Consequences

Positive:

• Low learning curve for partners (REST is widely understood)
• OpenAPI tooling enables auto-generated SDKs
• Cacheable via HTTP standards (ETags, Cache-Control)
• Easy to test with curl, Postman, or any HTTP client

Negative:

• Over-fetching and under-fetching compared to GraphQL
• Multiple roundtrips for complex data needs
• Versioning requires maintaining parallel implementations

Follow-up actions:

• Create the OpenAPI specification file
• Set up API documentation generation pipeline
• Define the error response format (see api-design skill)

Example ADR 3: Authentication Strategy

ADR-005: Use JWT with Short-Lived Access Tokens for Authentication

Status

Accepted

Context

We need to authenticate users and authorize API requests. The application has both a web frontend and mobile clients. Requirements:

• Stateless authentication to simplify horizontal scaling
• Support for token refresh without full re-authentication
• Revocation capability for compromised tokens
• Compatibility with OAuth2 for future third-party integrations

Options evaluated:

1. Session-based authentication with server-side storage
2. JWT with long-lived tokens
3. JWT with short-lived access tokens and refresh tokens

Decision

We will use JWT-based authentication with:

• Access tokens: 15-minute expiry, signed with RS256
• Refresh tokens: 7-day expiry, stored in the database, rotated on each use (refresh token rotation)
• Token storage: Access token in memory (frontend), refresh token in httpOnly secure cookie
• Revocation: Refresh tokens can be revoked by deleting from the database; access tokens are short-lived enough to not require explicit revocation in most cases
• Key rotation: RSA key pairs rotated quarterly with JWKS endpoint

Consequences

Positive:

• Stateless verification of access tokens (no database lookup per request)
• Refresh token rotation limits the window for stolen tokens
• RS256 allows verification without sharing the signing key
• JWKS endpoint enables key rotation without downtime

Negative:

• Cannot instantly revoke access tokens (15-minute window)
  • Mitigation: for critical actions (password change, detected breach), maintain a short-lived deny list checked by middleware
• Refresh token storage adds database dependency
• Token handling complexity on the client side
• Key rotation process needs careful implementation

Follow-up actions:

• Implement the JWKS endpoint
• Create middleware for token verification
• Document the token refresh flow for frontend and mobile teams
• Set up monitoring for failed authentication attempts

ADR Review Checklist

Before accepting an ADR, verify:

• Context explains the problem clearly enough that someone new can understand it

• All viable alternatives are listed and evaluated

• The decision is stated explicitly and unambiguously

• Both positive and negative consequences are acknowledged

• Follow-up actions are identified

• The ADR is linked to relevant issues or PRs

• The file follows naming conventions (NNNN-title-slug.md)

• Status is set to "Proposed" for review, "Accepted" after approval

• At least two team members have reviewed the ADR