oc-scale-ops

# Scale Ops

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

Assess and improve an app's ability to handle growth. Covers load testing,
performance budgets, caching strategy, query optimization, CDN config, and
capacity planning. Produces a scaling readiness report with a concrete upgrade
path from current capacity to target capacity.

## /oc-scale — Command Reference

```
SCALE OPS COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ASSESS
  /oc-scale audit          Full scaling readiness assessment
  /oc-scale budget         Set or audit performance budgets
  /oc-scale bottleneck     Identify the #1 scaling bottleneck

  TEST
  /oc-scale loadtest       Run load test against target URL
  /oc-scale benchmark      Benchmark specific endpoints

  OPTIMIZE
  /oc-scale cache          Design or audit caching strategy
  /oc-scale queries        Audit and optimize database queries
  /oc-scale cdn            CDN and edge optimization

  PLAN
  /oc-scale plan           Capacity plan from current → target users
  /oc-scale cost           Cost projection at target scale

  UTILITIES
  /checkpoint           Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-scale to see this again.
```

---

## Scaling Readiness Assessment (`/oc-scale audit`)

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

### What Gets Checked

| Layer | Checks | Tools |
|---|---|---|
| **Database** | Query complexity, missing indexes, N+1 patterns, connection pooling, row counts | EXPLAIN ANALYZE, schema review |
| **API** | Response times, payload sizes, pagination, rate limiting, caching headers | curl timing, endpoint inventory |
| **Frontend** | Bundle size, code splitting, lazy loading, image optimization, core web vitals | Lighthouse, bundle analysis |
| **Infrastructure** | Worker limits, D1 limits, KV limits, edge caching, CDN config | CF dashboard / API |
| **Architecture** | Stateless design, horizontal scalability, single points of failure | Code review |

### Cloudflare-Specific Limits

| Service | Free Tier | Paid Tier | Hard Ceiling |
|---|---|---|---|
| Workers requests | 100K/day | 10M/mo ($5) | Unlimited (pay per use) |
| Workers CPU time | 10ms/invocation | 30s/invocation | 30s |
| D1 reads | 5M/day | 25B/mo | Bound by SQLite limits |
| D1 writes | 100K/day | 50M/mo | 1 writer at a time |
| D1 database size | 500MB | 10GB | 10GB per DB |
| KV reads | 100K/day | 10M/mo | 1000 reads/sec per namespace |
| KV writes | 1K/day | 1M/mo | 1 write/sec per key |
| R2 storage | 10GB | Pay per use | Unlimited |
| Pages deployments | 500/mo | 5000/mo | Per project |

### Readiness Score

| Score | Meaning | Can Handle |
|---|---|---|
| A | Production-ready at scale | 10K+ concurrent users |
| B | Ready for moderate traffic | 1K-10K concurrent users |
| C | Works for small teams | 100-1K concurrent users |
| D | Works for personal use | 1-100 concurrent users (aidops-scale) |
| F | Has scaling blockers | Will break under real load |

### Readiness Report

```markdown
# 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 (`/oc-scale budget`)

Define measurable limits for each performance dimension:

### Default Budgets (adjust per project)

| Metric | Budget | Measurement |
|---|---|---|
| Time to First Byte (TTFB) | < 200ms | Server response time |
| First Contentful Paint (FCP) | < 1.5s | Browser paint |
| Largest Contentful Paint (LCP) | < 2.5s | Largest visible element |
| Cumulative Layout Shift (CLS) | < 0.1 | Visual stability |
| Interaction to Next Paint (INP) | < 200ms | Input responsiveness |
| API response time (p50) | < 100ms | Median endpoint latency |
| API response time (p95) | < 500ms | Tail latency |
| JS bundle size (gzipped) | < 150KB | Initial load |
| Total page weight | < 500KB | All resources |
| Database query time (p95) | < 50ms | Slowest queries |

### Budget Enforcement

```bash
# 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 oc-deploy-ops**: Performance budgets are part of the smoke test suite
- **In oc-code-auditor**: `/oc-audit perf` checks budget compliance

---

## Load Testing (`/oc-scale loadtest`)

### Using oha (Rust-based HTTP load tester)

```bash
# 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.work