design-documents

Design Documents

Core Principle

Design documents are a tool for thinking, not just documentation. Writing a design doc forces you to think through edge cases, alternatives, and second-order effects before writing code. The primary audience is your future self and your teammates who will maintain this system.

---

When to Write a Design Doc

A design doc is required when any of these conditions are met:

Trigger	Why
Change exceeds 500 lines of code	Large changes need upfront design to avoid expensive rework.
Introduces a new service or major module	New services create operational burden that must be justified.
Adds a new database table or significant schema change	Schema changes are hard to undo and affect many consumers.
Adopts a new external dependency or third-party service	External dependencies add risk, cost, and maintenance burden.
Changes API contracts in a breaking way	Breaking API changes affect consumers and require migration plans.
Makes a significant architectural decision affecting multiple teams	Cross-cutting decisions need visibility and buy-in.
Introduces a new data flow between services	Data flows create coupling and consistency challenges.

When NOT to write a design doc: Bug fixes, refactoring within a module (< 500 LOC), adding a feature that follows an established pattern, updating dependencies, or routine operational work. For these, a thorough PR description is sufficient.

---

Design Document Template

# Design: [Feature/System Name]

## Metadata

- **Author:** [Name]
- **Status:** Draft | In Review | Approved | Rejected | Superseded
- **Date:** YYYY-MM-DD
- **Reviewers:** [Names -- include at least one person from each affected team]
- **Approvers:** [Names -- who must approve before implementation begins]
- **Last Updated:** YYYY-MM-DD

---

## Context & Problem Statement

[What problem are we solving? Why is it a problem? Why now?
Include data that demonstrates the problem:
- Metrics showing the current pain (error rates, latency, support tickets).
- Business context (customer complaints, revenue impact, competitive pressure).
- What happens if we do nothing?

Be specific. "The system is slow" is not a problem statement.
"The product search API has a p99 latency of 4.2 seconds, causing a 15% cart
abandonment rate on mobile devices" is a problem statement.]

---

## Goals

[What must this solution achieve? Be specific and measurable.]

1. Reduce product search p99 latency to < 500ms.
2. Support 10,000 concurrent search queries.
3. Maintain backward compatibility with the existing search API.

---

## Non-Goals

[What is explicitly out of scope? This prevents scope creep and sets expectations.
Non-goals are features or improvements that are related but will NOT be addressed
by this design.]

1. Redesigning the search UI (separate project).
2. Supporting fuzzy/typo-tolerant search (future iteration).
3. Real-time index updates (batch updates within 5 minutes are acceptable).

---

## Proposed Solution

[Detailed description of what you will build. Include:]

### Architecture Overview

[Diagram showing components, data flows, and interactions.
Use ASCII diagrams or reference an attached image.]

[Client] --> [API Gateway] --> [Search Service] --> [Elasticsearch] | [Product Service] --> [PostgreSQL]

### How It Works

[Step-by-step description of the solution. Be specific enough that another
engineer could implement it from this description.]

1. [Step 1: ...]
2. [Step 2: ...]
3. [Step 3: ...]

### Key Design Decisions

[For each significant choice, explain what you chose and why.]

- **Why Elasticsearch over Algolia:** Self-hosted gives us control over ranking
  algorithms and avoids per-query pricing at our scale (2M queries/day).
- **Why batch indexing over real-time:** Simplifies consistency model and reduces
  infrastructure complexity. 5-minute delay is acceptable per product team.

---

## Alternatives Considered

[At least 2 alternatives. For each: describe the approach, list pros and cons,
and explain why it was rejected. This demonstrates that the proposed solution
is not the first idea that came to mind.]

### Alternative A: [Name]

**Description:** [What this approach would look like.]

**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

**Why rejected:** [Specific reason this approach was not chosen.]

### Alternative B: [Name]

**Description:** [What this approach would look like.]

**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

**Why rejected:** [Specific reason this approach was not chosen.]

---

## Data Model Changes

[New tables, columns, indexes. Include the actual schema.
For existing tables, show the before and after.]

### New Tables

```sql
CREATE TABLE search_index_jobs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    status VARCHAR(20) NOT NULL DEFAULT 'pending',  -- pending, running, completed, failed
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    records_processed INTEGER DEFAULT 0,
    error_message TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);