# Cloudflare Architecture

> 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.

- Skill: `zllovesuki/cloudflare-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zllovesuki/cloudflare-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zllovesuki/cloudflare-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zllovesuki (https://skillmd.com/u/zllovesuki)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zllovesuki/cloudflare-architecture

---

# 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:

```markdown
## 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.