Scale Ops

Scaling Readiness Assessment (/scale audit)

Comprehensive evaluation of how the app handles load. Produces a readiness score and prioritized optimization list.

What Gets Checked

Cloudflare-Specific Limits

Readiness Score

Readiness Report

# Scaling Readiness Report — [project]

## Current Profile
- Users: ~[N] (daily active)
- Requests: ~[N]/day
- Database: [size], [tables], [heaviest query]
- Infrastructure: [CF plan], [services used]

## Readiness Score: [A-F]
[One-sentence summary]

## Layer Scores
| Layer | Score | Bottleneck |
|---|---|---|
| Database | B | Missing index on sessions.user_id |
| API | C | No response caching, 4 N+1 queries |
| Frontend | A | Bundle 89KB gzipped, lazy loading active |
| Infrastructure | D | D1 free tier, 100K write limit/day |
| Architecture | B | Stateless workers, but single D1 database |

## Top 5 Bottlenecks (fix in order)
1. [Most impactful issue with fix]
2. ...

## Scaling Path: [current users] → [target users]
[What needs to change at each tier]

Performance Budgets (/scale budget)

Define measurable limits for each performance dimension:

Default Budgets (adjust per project)

Budget Enforcement

# Lighthouse CI (run in CI or locally)
npx lhci autorun --collect.url="<url>" \
  --assert.preset=lighthouse:recommended \
  --assert.assertions.first-contentful-paint=["error",{"maxNumericValue":1500}] \
  --assert.assertions.largest-contentful-paint=["error",{"maxNumericValue":2500}]

# Bundle size check
npx bundlesize --config bundlesize.config.json
# bundlesize.config.json:
# { "files": [{ "path": "dist/index.js", "maxSize": "150 kB" }] }

Budget Monitoring

After setting budgets, integrate into the pipeline:

• In CI: Lighthouse CI and bundle size checks block PRs that exceed budgets
• In deploy-ops: Performance budgets are part of the smoke test suite
• In code-auditor: /audit perf checks budget compliance

Load Testing (/scale loadtest)

Using oha (Rust-based HTTP load tester)

# Install
cargo install oha 2>/dev/null || brew install oha 2>/dev/null

# Basic load test: 100 concurrent connections, 30 seconds
oha -c 100 -z 30s https://your-app.workers.dev/api/health

# With custom headers (auth)
oha -c 50 -z 30s -H "Authorization: Bearer <token>" https://your-app.workers.dev/api/data

# Target specific RPS (requests per second)
oha -c 20 --rps 100 -z 60s https://your-app.workers.dev/api/health

Using hey (Go-based, simpler)

# Install
go install github.com/rakyll/hey@latest 2>/dev/null

# 1000 requests, 50 concurrent
hey -n 1000 -c 50 https://your-app.workers.dev/api/health

# With POST body
hey -n 500 -c 20 -m POST -H "Content-Type: application/json" \
  -d '{"test": true}' https://your-app.workers.dev/api/data

Using curl for quick benchmarks

# Simple timing
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  https://your-app.workers.dev/api/health

# Run 20 times, get averages
for i in $(seq 1 20); do
  curl -o /dev/null -s -w "%{time_total}\n" https://your-app.workers.dev/api/health
done | awk '{sum+=$1} END {print "Avg:", sum/NR, "s"}'

Load Test Report

## Load Test Results — [endpoint]

### Configuration
- Tool: oha
- Concurrency: 100
- Duration: 30s
- Target: https://app.workers.dev/api/health

### Results
| Metric | Value | Budget | Status |
|---|---|---|---|
| Requests/sec | 2,340 | 1,000 | ✅ |
| p50 latency | 42ms | 100ms | ✅ |
| p95 latency | 187ms | 500ms | ✅ |
| p99 latency | 890ms | 1000ms | ✅ |
| Error rate | 0.1% | < 1% | ✅ |
| Total requests | 70,200 | — | — |
| Timeouts | 3 | 0 | ⚠️ |

### Observations
- [What happened at peak load]
- [Where latency spiked]
- [Any errors and their patterns]

Caching Strategy (/scale cache)

Cache Layers for Cloudflare Stack

Request
  │
  ├──► CF CDN Cache (static assets, HTML if cacheable)
  │       TTL: hours-days
  │
  ├──► CF KV (app-level cache)
  │       TTL: minutes-hours
  │       Use for: API responses, computed values, session data
  │
  ├──► D1 Query Cache (automatic in Workers)
  │       TTL: per-request (not cross-request)
  │
  └──► Origin (D1 query)
        No cache, always fresh

What to Cache (Decision Framework)

KV Caching Pattern

async function withCache<T>(
  kv: KVNamespace,
  key: string,
  ttl: number,
  fetcher: () => Promise<T>
): Promise<T> {
  // Try cache first
  const cached = await kv.get(key, 'json');
  if (cached) return cached as T;

  // Cache miss — fetch and store
  const fresh = await fetcher();
  await kv.put(key, JSON.stringify(fresh), { expirationTtl: ttl });
  return fresh;
}

// Usage
const contacts = await withCache(env.CACHE, `contacts:${userId}`, 300, () =>
  db.select().from(contacts).where(eq(contacts.userId, userId))
);

Cache Invalidation

// Invalidate on write
app.post('/api/contacts', async (c) => {
  const contact = await createContact(c.env.DB, data);
  // Purge relevant cache keys
  await c.env.CACHE.delete(`contacts:${userId}`);
  await c.env.CACHE.delete(`contacts:${userId}:count`);
  return c.json(contact, 201);
});

Query Optimization (/scale queries)

Find Slow Queries

-- D1: no built-in slow query log, but you can time queries in code
-- Wrap queries with timing:

async function timedQuery<T>(db: D1Database, sql: string, params: any[]): Promise<{ result: T; ms: number }> {
  const start = performance.now();
  const result = await db.prepare(sql).bind(...params).all();
  const ms = performance.now() - start;
  if (ms > 50) console.warn(`Slow query (${ms.toFixed(0)}ms): ${sql.substring(0, 100)}`);
  return { result: result.results as T, ms };
}

Common Query Optimizations

EXPLAIN for D1

-- D1 supports EXPLAIN QUERY PLAN
EXPLAIN QUERY PLAN SELECT * FROM sessions WHERE user_id = ? AND created_at > ?;
-- Look for: SCAN TABLE (bad) vs SEARCH TABLE USING INDEX (good)

Capacity Planning (/scale plan)

Scaling Path Template

## Capacity Plan: [current] → [target] users

### Current State
- DAU: [N]
- Peak concurrent: [N]
- Requests/day: [N]
- DB size: [N] MB
- Monthly cost: $[N]

### Growth Tiers

| Tier | Users | Requests/day | DB Size | Changes Needed | Monthly Cost |
|---|---|---|---|---|---|
| Current | 2 | 500 | 5 MB | None | $0 (free tier) |
| Small | 100 | 50K | 50 MB | Add indexes, KV caching | $0 (free tier) |
| Medium | 1K | 500K | 500 MB | Paid Workers, optimize queries | $5-15 |
| Large | 10K | 5M | 5 GB | Multiple D1 DBs or Postgres, CDN | $50-200 |
| Scale | 100K+ | 50M+ | 50+ GB | External Postgres, queue system, read replicas | $200+ |

### Tier Transition Checklist

When moving from [current tier] to [next tier]:
1. [ ] [Specific infrastructure change]
2. [ ] [Query optimization needed]
3. [ ] [Caching to add]
4. [ ] [Cost increase to approve]
5. [ ] [Load test to validate]

Checkpoint Integration

Checkpoint Location

{project-dir}/.checkpoints/scale-ops.checkpoint.json

When to Write

Cross-Skill Reads

Principles

1. Measure before optimizing. Load test first. The bottleneck is rarely where you think it is.
2. Cache the read path, optimize the write path. Most apps are 90% reads. Caching reads buys the most headroom with the least complexity.
3. D1 is enough until it isn't. For aidops-scale (< 100 users), D1's free tier handles everything. Don't migrate to Postgres speculatively.
4. Performance budgets are guardrails, not goals. Set them once, enforce in CI, forget about them until they break.
5. Scale the bottleneck, not the stack. If the bottleneck is a missing index, adding a CDN won't help. Fix the actual constraint.
6. Cost scales with usage, not preparation. CF's pay-per-request model means you don't pay for capacity you don't use. Build the optimization, deploy it, and let usage determine cost.