Purpose
A System Design Doc works out and aligns the design of a system/feature before code — catching mistakes on paper (cheap) not in prod (expensive). A working document for discussion, read and critiqued before development starts. Tied to C4 (diagrams) and ADR (key forks).
Template
# System Design: <system/feature>
## Goals — what, why, success metrics, non-goals.
## Requirements — functional; NFR (load/latency/availability/data/security).
## Options (reuse-first) — A/B/C pros/cons.
## Chosen design — components (C4 Container), data flows, API contracts, data model.
## Scale & resilience — bottlenecks, degradation, backups.
## Risks & open questions.
Example 1 — core sync (fragment)
# System Design: Cloud sync of the personal core
## Goals — move favorites/notes across devices. Success: A→B < 2s, 0 data loss on conflict. Non-goals: user sharing.
## Requirements — NFR: ~5k active, sync < 2s, 99.9% availability, account isolation, ~5MB/user.
## Options — A last-write-wins (loses data ❌); B CRDT/Yjs (convergent ✅); C manual merge (friction ⚠️).
## Chosen — B (Yjs). Web App ↔ Sync API via WS + REST; state persisted in PostgreSQL, presence via Redis.
## Scale — bottleneck: WS connections → Redis adapter. Degradation: offline on IndexedDB. Backup: daily PG dump.
## Risks — Yjs history growth → compaction.
Example 2 — auto-clip (fragment)
# System Design: Auto-clip videos into Shorts
## Goals — ≥3 9:16 clips with subtitles. Success: 12-min video → clips in < 60s.
## Options — A sync in request (timeouts ❌); B background queue + status (resilient ✅).
## Chosen — B. Upload → queue (Redis) → worker: ffmpeg clip + external STT → store → status via WS. STT failure → retry, source kept.
## Risks — STT cost at scale; fallback to no-subtitles (open).
Quality checklist
- Goals AND non-goals, success metrics.
- NFR as numbers (RPS, latency, volume).
- Alternatives considered (reuse-first).
- Data flows & contracts shown (C4).
- Bottlenecks, degradation, backups named.
- Risks & open questions listed honestly.
Common mistakes
Design before requirements; one option; no bottlenecks/degradation; tombstone doc; hidden risks.