cloudflare-architecture

name	cloudflare-architecture
description	Choose Cloudflare Developer Platform primitives and architecture shapes before writing code. Use for Cloudflare Workers, Durable Objects, D1, R2, Queues, Workflows, Containers, Realtime, Workers AI, Vectorize, AI Search, Agents, cost, limits, and migration decisions.
compatibility	Cloudflare Workers TypeScript projects using Wrangler; verify current Cloudflare APIs, limits, and pricing before production use.
metadata	{"source":"Architecting on Cloudflare plus official Cloudflare Developer Platform docs","generated":"2026-04-28"}

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:

1. Does the workload fit Cloudflare's hard constraints? Check memory, CPU, body size, protocol, duration, regional/data residency, and product-specific limits.
2. What is the coordination atom? Identify the smallest entity that needs serialized state: user, tenant, room, document, game, checkout, import job, or workflow instance.
3. Where does each kind of data live? Separate relational records, blobs, cache, vector/search data, coordination state, and external database state.
4. What can be eventually consistent? Put eventual cache/read data in KV or caches; put consistency-sensitive logic in Durable Objects or D1 patterns.
5. 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.