From 0bf73b454c1004d5383309b0d61ee6ec030e5606 Mon Sep 17 00:00:00 2001
From: Jordan Robinson <hello@jordanrobinson.org>
Date: Sun, 19 Oct 2025 15:39:26 +0100
Subject: [PATCH] add capacity planning and scaling document template

---
 README.md                                     |   1 +
 .../capacity-planning-scaling-document.md     | 137 ++++++++++++++++++
 2 files changed, 138 insertions(+)
 create mode 100644 templates/capacity-planning-scaling-document.md

diff --git a/README.md b/README.md
index 82bd61841eed1c5de93616a851e9d8d9c9e80178..ff6c5acec6ba1a2d036a8e7bb6aa5cd249567768 100644
--- a/README.md
+++ b/README.md
@@ -12,3 +12,4 @@ Comprehensive collection of templates for solutions design, architecture decisio
 * Runbook / Operations Guide
 * Code Review Standards & Guidelines
 * Technical Debt Registry
+* Capacity Planning & Scaling Document
\ No newline at end of file
diff --git a/templates/capacity-planning-scaling-document.md b/templates/capacity-planning-scaling-document.md
new file mode 100644
index 0000000000000000000000000000000000000000..f0572421942ec79fae58c84d64031ef5c3204c94
--- /dev/null
+++ b/templates/capacity-planning-scaling-document.md
@@ -0,0 +1,137 @@
+# Capacity Planning & Scaling Document
+
+## Current State Assessment
+
+### System Metrics (as of [Date])
+- Current daily active users
+- Peak requests per second (RPS)
+- Average response time (p50/p95/p99)
+- Error rate
+- Data storage used
+- Resource utilization (CPU, memory, disk)
+
+### Infrastructure Details
+- Number of application servers
+- Database configuration (replicas, shards, etc.)
+- Cache configuration
+- CDN/load balancer setup
+- Region/availability zone setup
+
+## Growth Projections
+
+### Forecasted Growth
+- User growth rate
+- Expected peak RPS in 3/6/12 months
+- Data growth projections
+- Usage pattern changes expected
+
+### Traffic Patterns
+- Daily peaks and troughs
+- Seasonal variations
+- Special events that cause spikes
+
+## Scaling Limits
+
+### Current Bottlenecks
+- What limits us today?
+  - Database connection pool
+  - Memory constraints
+  - I/O limitations
+  - External service rate limits
+  - Network bandwidth
+
+### Projected Capacity Headroom
+- How long until we hit limits (in months)?
+- When do we need to take action?
+- Action items and timeline
+
+## Scaling Strategies
+
+### Horizontal Scaling
+**Application Layer:**
+- Load balancing strategy
+- Session management approach
+- Stateless design requirements
+- Max number of instances
+
+**Database Layer:**
+- Replication approach
+- Read replicas strategy
+- Sharding approach (if needed)
+- Consistency model
+
+**Cache Layer:**
+- Cache distribution strategy
+- Eviction policy
+- Warming strategy
+
+### Vertical Scaling
+- Current instance size
+- Available larger instances
+- When horizontal scaling isn't enough
+- Cost implications
+
+### Feature-Level Scaling
+- Feature flags for traffic shaping
+- Graceful degradation strategies
+- Circuit breakers
+- Rate limiting approach
+
+## Infrastructure Upgrades
+
+### Immediate (0-3 months)
+| Item | Current | Upgrade | Timeline | Cost |
+|------|---------|---------|----------|------|
+| [Item 1] | [Current] | [New] | [When] | [Cost] |
+
+### Medium-term (3-6 months)
+| Item | Current | Upgrade | Timeline | Cost |
+|------|---------|---------|----------|------|
+| [Item 1] | [Current] | [New] | [When] | [Cost] |
+
+### Long-term (6-12 months)
+| Item | Current | Upgrade | Timeline | Cost |
+|------|---------|---------|----------|------|
+| [Item 1] | [Current] | [New] | [When] | [Cost] |
+
+## Performance Optimization Opportunities
+- Low-hanging fruit for improvement
+- Estimated impact of each optimization
+- Timeline for implementation
+
+## Cost Implications
+- Current monthly infrastructure cost
+- Projected cost increase with growth
+- Cost optimization strategies
+- ROI of scaling investments
+
+## Testing & Validation
+
+### Load Testing Plan
+- How to simulate projected load
+- Testing methodology
+- Key metrics to measure
+- Acceptable failure modes
+
+### Staging Validation
+- How to test scaling procedures in staging
+- Frequency of capacity tests
+- Rollback procedures
+
+## Monitoring & Alarms
+
+### Early Warning Indicators
+- Metrics that signal capacity issues
+- Alert thresholds
+- Action triggers
+
+### Post-Scaling Validation
+- Metrics to verify scaling was successful
+- Dashboard updates needed
+- Communication to stakeholders
+
+## Owner & Review
+- Owner: [Team/Person]
+- Last reviewed: [Date]
+- Next review: [Date]
+- Previous versions/history: [Links]
\ No newline at end of file