cloudflare-workers-architect

What this skill does

# Cloudflare Workers Architect

Design and ship production systems on Cloudflare's developer platform. Picks the right primitive for each problem, names the limits that will bite, and emits `wrangler.toml`, bindings, deploy scripts, and a cost model. Acts as a senior platform engineer who has shipped multi-tenant SaaS, real-time collaboration, AI inference, and high-fan-out webhooks on Workers — and migrated stacks off Lambda@Edge, Vercel Edge, and Deno Deploy.

## Usage

Invoke when starting a new Workers project, deciding between primitives, sizing a real-time feature, picking storage, planning a migration, or hitting limits. Equally useful for "what should this be" architecture calls and "this Worker keeps timing out" debugging.

**Basic invocation:**
> Design a real-time collab editor on Cloudflare
> Should this be a Worker, a Pages function, or a Durable Object?
> Migrate our 80 Lambda@Edge handlers to Workers

**With context:**
> Here's the API surface — pick storage and write the wrangler.toml
> p99 hits the 30s wall-time limit; redesign with Queues
> We need 50k WebSocket connections with auth — plan the DO sharding

The agent emits a primitive choice, `wrangler.toml`, binding declarations, code skeletons, deploy commands, and a cost projection.

## Inputs Required

- **Workload shape** — HTTP API / static site / long-running stream / WebSocket / background job / scheduled / AI inference
- **State requirements** — stateless? per-user? per-room? global? eventual or strong?
- **Throughput** — req/s peak, concurrent connections, payload sizes
- **Latency target** — p50 / p95 / p99 budgets
- **Geographic distribution** — global, regional, single-country (data residency)
- **Existing constraints** — current platform if migrating, fixed external APIs, regulatory scope (GDPR, HIPAA)
- **Cost ceiling** — Workers free tier covers a lot; over $200/mo means real design choices

## Workflow

1. Classify the workload against the Decision Tree (below)
2. Pick storage from the Selection Matrix; declare bindings in `wrangler.toml`
3. Map every request path to a primitive (Worker / Pages Function / DO / Queue consumer / Cron Trigger)
4. Identify the limit that will bite first; design around it before code
5. Author `wrangler.toml` with all bindings, routes, and compatibility flags
6. Sketch the data flow: which subrequests fire, in what order, on which path
7. Wire observability: Workers Analytics Engine + Tail Worker for debug logs + Logpush to R2/external
8. Implement and test locally with `wrangler dev --remote` (real bindings)
9. Deploy via `wrangler deploy`; canary via gradual deploys
10. Document rollback (`wrangler rollback` to a known version ID)

## Decision Tree: Pages vs Workers vs Durable Objects vs Workers AI

```
START
 ├── Is the request path a static asset (HTML/JS/CSS/image)?
 │     └── YES → Pages (or Workers Sites if you need full control)
 │
 ├── Is it dynamic but stateless (lookup, transform, proxy, auth)?
 │     └── YES → Worker (HTTP fetch handler)
 │
 ├── Does it need per-entity state (per-user, per-room, per-document)
 │   that must be globally consistent and serialized?
 │     └── YES → Durable Object
 │             ├── If 1-to-1 with users → DO per user, ID = userId
 │             ├── If shared (collab doc, chat room) → DO per room
 │             └── If global counter / global queue → singleton DO
 │
 ├── Is it a long-running stream / WebSocket?
 │     └── YES → Durable Object with Hibernating WebSockets
 │             (free hibernation; pay only for actual messages)
 │
 ├── Is it AI inference (LLM, embedding, Whisper, image)?
 │     └── YES → Workers AI binding (calls into CF's inference fleet)
 │
 ├── Is it a scheduled job?
 │     └── YES → Worker with Cron Trigger
 │
 ├── Is it a queue-driven pipeline (webhooks, fan-out, retries)?
 │     └── YES → Worker producer + Queue + Worker consumer
 │
 └── Does it need to talk to a legacy Postgres/MySQL with low latency?
       └── YES → Hyperdrive binding (connection pool + region pinning)
```

**Pages vs Workers nuance:** Pages = static + opt-in `functions/`. Use Pages when the site is mostly static and you have a few API routes. Use Workers when API is the product, or you need advanced bindings (DOs, Queues, RPC).

**Pages Functions are Workers** under the hood — same runtime, same limits, fewer config knobs. Migrate Pages Functions → Worker when you need: cron triggers, queue consumers, smart placement, custom routes, or service bindings.

## Storage Selection Matrix

| Storage | Read latency | Write latency | Size cap | Consistency | Cost | When |
|---------|-------------|---------------|----------|-------------|------|------|
| **Workers KV** | <50ms (cached) | seconds (eventual) | 25 MiB/value | Eventual (60s) | $0.50/M reads, $5/M writes | Read-heavy global config, feature flags, cached HTML |
| **D1** | 5-50ms | 5-50ms | 10 GB/db | Strong within region | $0.001/1k reads, $1/1M writes | Relational app data, low-write |
| **R2** | 50-200ms | 50-500ms | 5 TiB/object | Strong (immediate) | $0.015/GB/mo, no egress | User uploads, backups, datasets |
| **Durable Object Storage** | <10ms (in-DO) | <50ms | 1 GB/DO | Strong, serialized | Bundled with DO compute | Per-entity state, real-time |
| **Durable Object SQLite** | <5ms | <20ms | 1 GB/DO | Strong, ACID | Bundled | Relational state per entity (newer alt to KV-style DO storage) |
| **Vectorize** | 10-50ms | seconds | 5M vectors/index | Eventual | $0.04/M queried | Embeddings, semantic search |
| **Hyperdrive (Postgres pool)** | 5-20ms (cached) | 10-30ms | external DB | external | $0 + your DB cost | Legacy Postgres/MySQL |
| **Cache API** | <5ms (in PoP) | <10ms | per PoP | per-PoP | free | Per-PoP HTTP response cache |

**Decision rules:**
- **Reads >> writes, global, eventual ok** → KV
- **Relational queries, joins, transactions, low-write** → D1
- **Files, blobs, datasets, images** → R2
- **Per-entity state with strong serialization** → DO Storage (use SQLite variant for relational shape)
- **Embeddings / semantic search** → Vectorize
- **Existing Postgres/MySQL you can't replace** → Hyperdrive
- **Per-PoP HTTP cache (idempotent GET)** → Cache API

**Anti-pattern alert:**
- Don't use KV as a write-heavy store — eventual consistency + write rate limits will burn you
- Don't use D1 for >100 writes/sec sustained — split into per-tenant DOs with SQLite
- Don't use R2 for tiny key-value records — KV is cheaper at small sizes
- Don't use a singleton DO for global state with >1k req/s — that DO's CPU is the bottleneck; shard

## Edge State Patterns

**Pattern 1: Singleton DO** — one DO globally, ID = constant string.
- Use for: global counters, config registries, leader election, low-traffic shared state
- Limit: ~1k req/s per DO; bounded by single-threaded execution
- Failure mode: hot-shard kills throughput

**Pattern 2: DO per entity** — `idFromName(userId)`, `idFromName(roomId)`.
- Use for: per-user state, per-document collab, per-tenant data
- Naturally horizontal: throughput scales with entity count
- Place hint: `locationHint: "weur"` to colocate with the user

**Pattern 3: Sharded DOs** — `idFromName(\`shard-${hash(key) % N}\`)`.
- Use for: high-throughput counters, rate limiters, high-fan-out queues
- N = (target throughput) / (1k req/s per DO) + headroom
- Aggregate via cron Worker that fans out to all shards

**Pattern 4: Hibernating WebSocket DO**
- DO accepts WebSocket via `state.acceptWebSocket(ws)` (NOT `ws.accept()`)
- DO can be evicted from memory between messages — only billed when active
- State persists in DO Storage, not in JS variables
- Up to ~32k connections per DO before throughput pressure

```js
// hibernating WS pattern
export class ChatRoom {
  constructor(state, env) { this.state = state; }
  async fetch(req) {
    const pair = new WebSocketPair();
    this.state.acceptWebSocket(pair[1]);              // hibernation-aware
    return new Response(null, { status: 101, webSocket: pair[0] });
  }
  async webSo