Architecture

Architecture Decision Framework

"Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."

🎯 Selective Reading Rule

Read ONLY files relevant to the request! Check the content map, find what you need.

🔗 Related Skills

Core Principle

"Simplicity is the ultimate sophistication."

• Start simple
• Add complexity ONLY when proven necessary
• You can always add patterns later
• Removing complexity is MUCH harder than adding it

📐 System Design Template (Staff Level)

Don't start with boxes. Start with math and requirements.

1. Requirements & Constraints
   • Functional: "User clips video", "System generates subtitles"
   • Non-Functional: "Wait time < 20s", "99.9% Availability", "Budget < $500/mo"
2. Back-of-Envelope Math (Capacity)
   • Formula: $QPS = DailyActiveUsers \times ActionsPerUser / 86400$
   • Formula: $Storage = WritesPerDay \times SizePerWrite \times RetentionDays$
   • Example: 10k users, 2GB videos = 20TB storage? -> S3 Cold Storage needed.
3. High-Level Design (The "Blob" Phase)
   • Client -> API Gateway -> Service -> DB.
   • Validate against constraints (Will single DB handle calc QPS? No -> Read Replica).
4. Detailed Design (The "Hard Parts")
   • "How exactly do we handle the video processing failure?" (Dead Letter Queue + Retry)
   • "How do we handle 1 million users?" (Sharding vs Partitioning)

⚖️ Decision Matrix (Trade-off Guide)

📊 Capacity Planning Cheatsheet

• QPS to Servers: $Servers = TargetQPS / (SingleCoreQPS \times Cores \times UtilizationFactor)$
• Bandwidth: $Mbps = TotalBytesPerSec * 8 / 1,000,000$
• Database: Read-heavy? Cache/Replica. Write-heavy? Sharding/Queue-buffering.

Validation Checklist

Before finalizing architecture:

• Requirements clearly understood
• Constraints identified
• Each decision has trade-off analysis
• Simpler alternatives considered
• ADRs written for significant decisions
• Team expertise matches chosen patterns