Phase 1: Planning, Design Documents, and Architecture Decision Records (ADRs)

High-performing software engineering teams do not write code until the problem domain, trade-offs, and architecture have been thoroughly vetted. Design Documents (RFCs) clarify ambiguity before implementation, while Architecture Decision Records (ADRs) record immutable technical decisions in source control.

⚡ Quick Dive

The Planning Artifacts Matrix

Artifact Primary Purpose Audience Lifecycle
Design Doc / RFC Solicit peer feedback on proposed system designs and trade-offs Engineering team, Cross-functional Active during proposal; archived after implementation
Architecture Decision Record (ADR) Record the context and rationale for an immutable architectural choice Present & Future engineers Permanently version-controlled in git repository
C4 Architectural Diagram Multi-level visual representation of system boundaries Engineers, Architects, Leadership Updated as system architecture evolves

📖 Extended Guide

1. The Standard RFC / Design Document Template

# RFC: [Project / Feature Title]
**Author**: [Your Name] | **Status**: [Draft / In Review / Approved] | **Date**: YYYY-MM-DD

## 1. Executive Summary & Problem Statement
Concise 2-3 paragraph overview of the problem, why it matters, and the proposed solution.

## 2. Goals & Non-Goals
- **Goals**: Quantifiable deliverables (e.g. "Process 10,000 orders/sec at < 50ms p99 latency").
- **Non-Goals**: Explicit boundaries of what this project will NOT address.

## 3. High-Level Architecture
System architecture diagram and component interaction flow.

## 4. Detailed Design & Interface Schemas
- API contracts (OpenAPI / Protobuf)
- Database schema changes & index strategy
- Error handling, idempotency & retries

## 5. Alternatives Considered & Trade-Offs
Why alternative approaches X and Y were rejected in favor of the chosen design.

## 6. Security, Privacy & Observability
- Threat model & authentication
- Prometheus metrics, log formats, and SLO impact

2. Architecture Decision Record (MADR Format)

Save in docs/adr/0001-use-postgresql-for-order-storage.md:

# ADR 0001: Use PostgreSQL for Order Storage
* **Status**: Accepted
* **Date**: YYYY-MM-DD
* **Deciders**: [Engineering Lead, Senior Backend Engineer]

## Context and Problem Statement
We need an ACID-compliant primary datastore for order transactions requiring strict consistency.

## Decision Drivers
* Financial transaction accuracy (No dirty reads)
* Support for JSONB and relational foreign keys
* Team familiarity and battle-tested RDS hosting

## Considered Options
1. PostgreSQL 16
2. MongoDB 7.0
3. DynamoDB

## Decision Outcome
Chosen option: **PostgreSQL 16**, because ACID compliance and serializable isolation eliminate double-charge risks.
⌂ All Guides