zllovesuki Cloudflare Architecture
Use this skill before implementing a Cloudflare application or migrating an existing system. The goal is to map requirements to primitives, not to recreate an AWS/Azure/GCP architecture one service at a time.
Default stance
- Treat Cloudflare as a set of composable primitives: compute, coordination, storage, queues, workflows, object storage, AI, and bindings.
- Build horizontal systems. Prefer many small state partitions over one central bottleneck.
- Prefer bindings over public HTTP calls when one Worker talks to Cloudflare resources or another Worker.
- Keep stateless code in Workers and move coordination/state serialization to Durable Objects.
- Do not assume every workload belongs on Cloudflare. Reject Cloudflare early when hard runtime, protocol, memory, or operational constraints dominate.
First-pass architecture decision
Ask and answer these in the design notes before writing code:
- Does the workload fit Cloudflare's hard constraints? Check memory, CPU, body size, protocol, duration, regional/data residency, and product-specific limits.
- What is the coordination atom? Identify the smallest entity that needs serialized state: user, tenant, room, document, game, checkout, import job, or workflow instance.
- Where does each kind of data live? Separate relational records, blobs, cache, vector/search data, coordination state, and external database state.
- What can be eventually consistent? Put eventual cache/read data in KV or caches; put consistency-sensitive logic in Durable Objects or D1 patterns.
- What is the failure model? Define retries, idempotency keys, replay behavior, dead-letter or compensating actions, and observability.
Primitive chooser
| Need | Prefer | Avoid |
|---|---|---|
| Stateless API, SSR, auth proxy, transform | Workers | Durable Objects unless shared state is required |
| Strongly consistent per-entity coordination | Durable Objects | KV counters, global D1 locks, process globals |
| Relational SQLite data | D1 | R2/KV for queryable relational data |
| Large files, media, exports, backups | R2 | D1/KV for blobs |
| Fast globally cached values | KV | KV as source of truth for coordination |
| Existing Postgres/MySQL database | Hyperdrive | Direct cross-region DB connections from every request |
| Background fan-out or deferred work | Queues | Queues for ordered workflows or shared progress state |
| Ordered durable multi-step process | Workflows | Manual retry state scattered across queues and D1 |
| Native binaries, long-running processes, larger runtime shape | Containers | Containers as first choice for normal HTTP APIs |
| Data realtime: chat, multiplayer, collaborative docs | Durable Objects + WebSockets | One global singleton object |
| Media realtime: audio/video/WebRTC | Cloudflare Realtime | WebSockets for audio/video media transport |
| LLM inference from Worker | Workers AI or external model through AI Gateway | Assuming Workers AI always has best model quality |
| RAG/search | AI Search for managed retrieval, Vectorize for custom vector search | Blind prompt-only answers without retrieval checks |
| Autonomous multi-step tool user | Agents SDK | Agent for simple chatbot, lookup, or deterministic workflow |
Architecture output template
When producing architecture code or a plan, include:
## Cloudflare primitive map
- Worker routes:
- Durable Object classes and identity keys:
- D1 databases / table boundaries:
- R2 buckets and object key scheme:
- KV namespaces and TTL policy:
- Queues / Workflows:
- AI / Vectorize / AI Search / Agents:
- External systems via Hyperdrive or fetch:
## Critical constraints checked
- Runtime limits:
- Storage limits:
- Consistency assumptions:
- Cost drivers:
- Failure/retry/idempotency:
Red flags
- A single Durable Object handles all users, all traffic, or all tenant data.
- A Worker uses mutable global variables for user/session/application state.
- KV is used for counters, locks, inventory, balances, or anything requiring read-after-write correctness globally.
- D1 is treated as one unlimited global relational database without tenant or data-boundary planning.
- Queue consumers assume strict ordering or exactly-once processing.
- AI code lacks token budgets, retrieval grounding, model fallback, or observability.
- Migration plan lacks rollback, shadow reads, or baseline metrics.