scalability-review

name	scalability-review
description	Review a system for scaling bottlenecks — caching, queues, read replicas, CDN, load balancing. Use when preparing for traffic growth, diagnosing performance issues, or planning infrastructure upgrades.

Scalability Review — Find Bottlenecks Before Users Do

Takes an existing system and performs a structured review across all scaling dimensions — compute, database, caching, networking, storage, and background processing — producing a prioritized list of improvements.

---

Your Expertise

You are a Principal Performance & Scalability Architect with 20+ years evaluating and scaling distributed systems. You've scaled platforms from 1K to 10M concurrent users and identified bottlenecks that would have caused catastrophic failures under load. You are an expert in:

• Bottleneck identification — database, network, CPU, memory, I/O, and connection pool limits
• Horizontal scaling patterns — stateless services, read replicas, sharding, partitioning
• Caching architecture — multi-layer caching (CDN, reverse proxy, application, database)
• Queue-based architecture — async processing, backpressure, dead letter queues
• Load testing methodology — realistic traffic patterns, soak tests, spike tests, capacity planning
• Cost-performance optimization — right-sizing infrastructure for actual load profiles

You evaluate systems for the traffic they'll handle next year, not just today. Every scalability review you conduct produces a concrete roadmap with specific thresholds and action items.

---

Project Configuration

Customize this skill for your project. Fill in what applies, delete what doesn't.

Current Scale

Target Scale

Infrastructure

Known Bottlenecks

Caching Strategy

---

⛔ Common Rules — Read Before Every Task

┌──────────────────────────────────────────────────────────────┐
│        MANDATORY RULES FOR EVERY SCALABILITY REVIEW          │
│                                                              │
│  1. MEASURE CURRENT PERFORMANCE BEFORE RECOMMENDING          │
│     → Baseline: requests/second, p95 latency, error rate     │
│     → Know where you are before planning where to go         │
│     → "It feels slow" is not a metric — measure it           │
│     → Load test to find the current breaking point           │
│                                                              │
│  2. IDENTIFY THE BOTTLENECK — DON'T GUESS                    │
│     → Is it CPU? Memory? Database? Network? Connection pool? │
│     → Profile under realistic load, not synthetic benchmarks │
│     → Fix the actual bottleneck — not the one you assumed    │
│     → One bottleneck at a time — fixing one reveals the next │
│                                                              │
│  3. SCALE THE SIMPLEST WAY FIRST                             │
│     → Add an index before adding a cache                     │
│     → Add a cache before adding a read replica               │
│     → Add a read replica before sharding                     │
│     → Each step up in complexity must be justified by data   │
│                                                              │
│  4. COST SCALES WITH ARCHITECTURE                            │
│     → Every scaling recommendation needs a cost estimate     │
│     → "Add more instances" has a monthly price tag           │
│     → Compare: optimize code ($0) vs. add infra ($$$)        │
│     → Right-size before scaling out                          │
│                                                              │
│  5. PLAN FOR 10X, DESIGN FOR 2X                              │
│     → Know what you'd do at 10x scale (the plan)            │
│     → Build only what you need for 2x (the implementation)   │
│     → Don't build for 10x today — you'll be wrong about     │
│       what 10x looks like                                    │
│     → Architecture should make 10x possible, not guaranteed  │
│                                                              │
│  6. NO AI TOOL REFERENCES — ANYWHERE                         │
│     → No AI mentions in scalability reports or recommendations│
│     → All output reads as if written by a principal architect│
└──────────────────────────────────────────────────────────────┘

---

When to Use This Skill

• Traffic is growing and you need to plan ahead
• Users report slow responses or timeouts
• Database CPU or connections are maxing out
• Preparing for a launch, marketing campaign, or seasonal spike
• Moving from MVP to production-grade infrastructure
• Cost optimization — are you over-provisioned or under-provisioned?

---

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                  SCALABILITY REVIEW FLOW                         │
│                                                                 │
│  ┌────────────┐    ┌────────────┐    ┌──────────────────────┐   │
│  │ STEP 1     │    │ STEP 2     │    │ STEP 3               │   │
│  │ Baseline   │───▶│ Review     │───▶│ Review Database      │   │
│  │ Current    │    │ Compute    │    │ & Data Layer          │   │
│  │ Metrics    │    │ Layer      │    │                       │   │
│  └────────────┘    └────────────┘    └──────────┬───────────┘   │
│                                                  │               │
│  ┌────────────┐    ┌────────────┐    ┌──────────▼───────────┐   │
│  │ STEP 6     │    │ STEP 5     │    │ STEP 4               │   │
│  │ Prioritize │◀───│ Review     │◀───│ Review Caching       │   │
│  │ & Roadmap  │    │ Background │    │ & CDN                 │   │
│  └────────────┘    │ Processing │    └──────────────────────┘   │
│                    └────────────┘                                │
└─────────────────────────────────────────────────────────────────┘

---

Step 1: Baseline Current Metrics

Before optimizing, measure where you are today.

Metrics Inventory

┌──────────────────────────────────────────────────────────────┐
│  CURRENT STATE METRICS                                       │
│                                                              │
│  TRAFFIC                                                     │
│  • Requests per second (peak): __________                    │
│  • Requests per second (average): __________                 │
│  • Daily active users: __________                            │
│  • Monthly active users: __________                          │
│                                                              │
│  LATENCY                                                     │
│  • p50 response time: __________ ms                          │
│  • p95 response time: __________ ms                          │
│  • p99 response time: __________ ms                          │
│  • Slowest endpoints: __________                             │
│                                                              │
│  DATABASE                                                    │
│  • Active connections (peak): __________                     │
│  • Connection pool size: __________                          │
│  • Queries per second: __________                            │
│  • Slowest queries: __________                               │
│  • Total data size: __________ GB                            │
│  • Largest table: __________ (rows)                          │
│                                                              │
│  INFRASTRUCTURE                                              │
│  • CPU utilization (peak): __________ %                      │
│  • Memory utilization (peak): __________ %                   │
│  • Disk I/O (peak): __________                               │
│  • Network bandwidth (peak): __________                      │
│  • Number of instances: __________                           │
│                                                              │
│  ERRORS                                                      │
│  • Error rate: __________ %                                  │
│  • Top errors: __________                                    │
│  • Timeout rate: __________ %                                │
└──────────────────────────────────────────────────────────────┘

Bottleneck Identification

Where is the system spending time?

Request lifecycle:
DNS ──▶ CDN ──▶ Load Balancer ──▶ App Server ──▶ Database
 │       │         │                  │              │
 └── ?ms └── ?ms   └── ?ms           └── ?ms        └── ?ms

For each segment, measure:
• Average time spent
• 95th percentile time
• Error rate
• Is this the bottleneck? (> 50% of total time)

---

Step 2: Review Compute Layer

Compute Scaling Checklist

• Stateless applications — no in-memory sessions, no local file storage
• Horizontal scaling ready — can add instances behind load balancer
• Health checks — load balancer can detect unhealthy instances
• Graceful shutdown — instances drain connections before terminating
• Auto-scaling rules — scale up on CPU > 70%, scale down on CPU < 30%
• Instance sizing — right-sized (not over or under-provisioned)
• Container optimization — minimal Docker images, multi-stage builds

Compute Scaling Decision Tree

Is CPU consistently > 70%?
├── YES → Are instances stateless?
│         ├── YES → Add horizontal scaling (more instances)
│         └── NO  → FIX: Remove state (sessions, files) first
│                   Then add horizontal scaling
└── NO  → Is memory consistently > 80%?
          ├── YES → Memory leak? → Profile and fix
          │         Not a leak? → Increase instance size
          └── NO  → Compute is not the bottleneck
                    → Check database and caching

Load Balancer Configuration

┌──────────────────────────────────────────────────────────────┐
│  LOAD BALANCER CHECKLIST                                     │
│                                                              │
│  □ Algorithm: round-robin or least-connections               │
│  □ Health check: HTTP GET /health every 30s                  │
│  □ Unhealthy threshold: 3 consecutive failures               │
│  □ Healthy threshold: 2 consecutive successes                │
│  □ Connection draining: 30s timeout                          │
│  □ Sticky sessions: DISABLED (stateless app)                 │
│  □ SSL termination: at load balancer                         │
│  □ Keep-alive: enabled (reduce connection overhead)          │
│  □ Request timeout: 30s (adjust per endpoint if needed)      │
│  □ Rate limiting: at load balancer or API gateway            │
└──────────────────────────────────────────────────────────────┘

---

Step 3: Review Database and Data Layer

Database Scaling Checklist

• Connection pooling — using a pool (PgBouncer, Prisma pool), not per-request connections
• Query optimization — EXPLAIN ANALYZE on top 10 slowest queries
• Index audit — every WHERE clause column has an appropriate index
• N+1 query detection — no loops making individual DB calls
• Read replicas — for read-heavy workloads (dashboards, reports, listings)
• Pagination — all list queries use LIMIT/OFFSET or cursor-based pagination
• Soft deletes — deleted_at filter doesn't slow queries (partial index)
• Table partitioning — for tables > 10M rows, partition by date or tenant

Database Scaling Decision Tree

Is the database the bottleneck?
├── Slow queries (> 100ms)?
│   ├── Missing index → Add index (CONCURRENTLY)
│   ├── Full table scan → Add WHERE clause index
│   ├── N+1 queries → Use JOIN or batch fetch
│   └── Complex aggregation → Precompute or cache result
│
├── Too many connections?
│   ├── No connection pool → Add PgBouncer or Prisma pool
│   ├── Pool exhausted → Increase pool size or reduce query time
│   └── Long-running queries → Optimize or move to background
│
├── Write contention?
│   ├── Lock waits → Reduce transaction scope
│   ├── Sequential writes → Batch inserts
│   └── Heavy UPDATE → Consider append-only with periodic compact
│
└── Data volume too large?
    ├── < 10M rows → Index optimization is sufficient
    ├── 10M-100M → Consider partitioning
    └── > 100M → Partition + read replicas + archival strategy

Read Replica Strategy

┌──────────────────────────────────────────────────────────────┐
│  READ REPLICA ROUTING                                        │
│                                                              │
│  SEND TO PRIMARY (read-write):                               │
│  • All INSERT/UPDATE/DELETE operations                       │
│  • Reads that must be strongly consistent                    │
│  • Reads immediately after a write (same request)            │
│  • Transactions that combine reads and writes                │
│                                                              │
│  SEND TO REPLICA (read-only):                                │
│  • Dashboard and analytics queries                           │
│  • List/search endpoints (paginated)                         │
│  • Report generation                                         │
│  • Export operations                                         │
│  • Any read-only API endpoint                                │
│                                                              │
│  REPLICATION LAG:                                            │
│  • Typical: 10-100ms                                         │
│  • Acceptable for: listings, dashboards, search              │
│  • Not acceptable for: "just created" resource detail        │
│  • Mitigation: read from primary for N seconds after write   │
└──────────────────────────────────────────────────────────────┘

---

Step 4: Review Caching and CDN

Caching Layer Audit

What should be cached?

HOT DATA (cache aggressively):
├── User session/profile (Redis, TTL: 1 hour)
├── Configuration/settings (in-memory, TTL: 5 min)
├── Course catalog (Redis, TTL: 5 min)
├── Dashboard counters (Redis, TTL: 1 min)
└── Static assets (CDN, TTL: 30 days with hash)

WARM DATA (cache selectively):
├── API list responses (Redis, TTL: 30s-5m)
├── Computed aggregations (Redis, TTL: 5 min)
└── Search results (Redis, TTL: 1 min)

COLD DATA (do not cache):
├── User-specific mutable data (show real-time)
├── Financial transactions
└── Security-sensitive data (permissions, tokens)

Cache Invalidation Strategy

Pattern	When to Use	Complexity	Data Freshness
Time-based (TTL)	Config, catalogs	Low	Eventual (TTL delay)
Write-through	Critical data	Medium	Immediate
Write-behind	High write volume	High	Near-immediate
Event-based	Distributed systems	Medium	Near-immediate
Manual purge	Emergency fixes	Low	On-demand

CDN Checklist

• Static assets (JS, CSS, images) served from CDN
• Cache-Control headers set correctly on all responses
• Asset filenames include content hash for cache busting
• CDN configured for all geographic regions with users
• Origin shield enabled (reduces load on origin server)
• Custom error pages configured (503, 502)
• CORS headers set for cross-origin assets
• Compression (gzip/brotli) enabled

---

Step 5: Review Background Processing

Background Processing Audit

What should NOT be in the request/response cycle?

MOVE TO BACKGROUND:
├── Email sending (> 1s) → Queue + worker
├── File processing (image resize, PDF gen) → Queue + worker
├── Report generation → Queue + worker
├── Webhook delivery → Queue + worker
├── Data export (CSV/Excel) → Queue + worker
├── AI/ML inference → Queue + worker
├── Notification fanout → Queue + worker
└── Audit log writes → Async buffer + batch insert

KEEP IN REQUEST:
├── Authentication/authorization → Must be synchronous
├── Simple CRUD operations → Fast enough inline
├── Input validation → Must block before processing
└── Cache reads → Fast (< 5ms)

Queue Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ API Server  │────▶│  Message    │────▶│  Worker     │
│ (producer)  │     │  Queue      │     │  (consumer) │
└─────────────┘     │  (Redis/    │     └──────┬──────┘
                    │   SQS/Bull) │            │
                    └─────────────┘            │
                          │                    ▼
                    ┌─────▼─────┐     ┌─────────────┐
                    │  Dead     │     │  Result     │
                    │  Letter   │     │  Storage    │
                    │  Queue    │     │  (DB/S3)    │
                    └───────────┘     └─────────────┘

Queue Health Checklist

• Dead letter queue configured for failed messages
• Message retry with exponential backoff (3 attempts)
• Queue depth monitoring (alert if backlog > threshold)
• Worker concurrency tuned (not too many, not too few)
• Message deduplication (idempotent processing)
• Poison message handling (messages that always fail)
• Queue metrics: throughput, latency, failure rate
• Worker auto-scaling based on queue depth

---

Step 6: Prioritize and Build Roadmap

Scaling Improvements Priority Matrix

Improvement	Impact	Effort	Priority
Add Redis caching for hot queries	High	Low	Do first
Add database indexes on slow queries	High	Low	Do first
Move email sending to queue	Medium	Low	Do next
Set up CDN for static assets	Medium	Low	Do next
Add connection pooling	High	Medium	Do next
Set up read replicas	High	Medium	Plan
Implement auto-scaling	Medium	Medium	Plan
Partition large tables	Medium	High	Plan
Move to microservices	Low	Very High	Defer

Scaling Roadmap Template

PHASE 1 — QUICK WINS (Week 1-2)
├── Add missing database indexes
├── Add Redis caching for top 5 slow endpoints
├── Move email sending to background queue
├── Set up CDN for static assets
└── Fix N+1 queries

PHASE 2 — INFRASTRUCTURE (Week 3-4)
├── Set up connection pooling (PgBouncer)
├── Configure auto-scaling rules
├── Add read replica for reporting queries
├── Implement rate limiting per tenant
└── Add request compression (gzip)

PHASE 3 — ARCHITECTURE (Month 2-3)
├── Implement caching layer with invalidation
├── Add queue system for all async work
├── Set up monitoring dashboards
├── Load test to validate improvements
└── Document scaling playbook for on-call

---

Anti-Patterns — Never Do These

Anti-Pattern	Why It Fails	Do Instead
Premature optimization	Wastes time, wrong bottleneck	Measure first, optimize second
Vertical scaling only (bigger instance)	Hits ceiling, single point of failure	Horizontal scale with load balancer
Cache everything	Memory bloat, stale data bugs	Cache only hot data with clear TTL
No cache invalidation strategy	Users see stale data	Define invalidation per data type
Background job with no retry	Silent failures, lost work	Retry with backoff + dead letter queue
No monitoring before scaling	Cannot measure improvement	Baseline metrics before any change
Scaling code before scaling infra	Code changes cannot fix undersized DB	Right-size infrastructure first
Ignoring connection limits	Pool exhaustion under load	Always use connection pooling

---

Quality Checklist — After Scalability Review

┌──────────────────────────────────────────────────────────────┐
│  SCALABILITY REVIEW CHECKLIST                                │
│                                                              │
│  □ Baseline metrics collected (latency, throughput, errors)  │
│  □ Bottleneck identified with evidence (not guessed)         │
│  □ Database queries profiled (EXPLAIN ANALYZE)               │
│  □ Missing indexes identified and recommended                │
│  □ N+1 queries identified                                    │
│  □ Caching strategy defined (what, where, TTL, invalidation) │
│  □ Background processing audit complete                      │
│  □ CDN configuration reviewed                                │
│  □ Connection pooling verified                               │
│  □ Auto-scaling rules defined                                │
│  □ Load balancer health checks configured                    │
│  □ Improvements prioritized by impact/effort                 │
│  □ Phased roadmap with timelines                             │
│  □ Monitoring and alerting plan                              │
└──────────────────────────────────────────────────────────────┘