Cloudflare Workers architecture guide
This guide helps teams design Cloudflare Workers applications around production architecture decisions: native rules versus code, routes, bindings, storage, authentication, secrets, error handling, logging, CI/CD, rollback, and managed operations.
This guide helps teams design Cloudflare Workers applications around production architecture decisions: native rules versus code, routes, bindings, storage, authentication, secrets, error handling, logging, CI/CD, rollback, and managed operations.
Topics: cloudflare, resource, cloudflare, workers, architecture, guide
Machine-readable context: /ai-index.json
Step by step
Implementation steps
- 1
Decide the native-rules-versus-code boundary first: keep header edits, redirects, routing, and cache decisions in Transform, Cache, Redirect, and Origin Rules, and use Workers only where code, state, or external calls are required.
- 2
Define routes and execution model: which hostnames and path patterns invoke each Worker, whether it runs ahead of cache or as origin, and how Workers compose through service bindings rather than network hops.
- 3
Choose storage per data shape — KV for read-heavy eventually consistent config, D1 for relational queries, R2 for objects and large blobs, and Durable Objects for per-key coordination and strong consistency.
- 4
Design asynchronous and long-running work with Queues for buffered processing and Workflows for durable multi-step execution, keeping request-path Workers fast and within CPU and subrequest budgets.
- 5
Specify the security model: input validation, authentication and authorization, secrets via Wrangler bindings, and per-environment configuration kept out of source.
- 6
Plan error handling and resilience: timeouts and retries on subrequests, idempotency for Queue consumers and Workflow steps, and graceful degradation when a binding or origin is unavailable.
- 7
Build observability into the design: Workers logs/Logpush, tail consumers, error reporting, and analytics wired before production traffic.
- 8
Define CI/CD and rollback with Wrangler: preview environments, versioned and gradual (percentage) deployments, and a clear revert path per Worker.
Risk register
Risks to control
Logic that belongs in native rules is built as Workers, adding code and cost where none is needed.
Set the rules-versus-code boundary in the design and push header, redirect, routing, and cache decisions to Transform, Cache, Redirect, and Origin Rules.
The wrong storage primitive is chosen — for example KV used where strong consistency is required.
Match data shape to primitive: KV for eventually consistent reads, D1 for relational, R2 for objects, and Durable Objects for coordination and strong consistency.
Request-path Workers exceed CPU-time or subrequest limits under real traffic.
Keep hot paths lean, offload heavy or multi-step work to Queues and Workflows, and profile CPU and subrequest counts in staging.
Queue consumers or Workflow steps are not idempotent and reprocess on retry.
Design consumers and steps to be idempotent and use Durable Objects or storage keys to dedupe, since at-least-once delivery and retries are expected.
Workers are chained over HTTP, adding latency and failure points between services.
Compose Workers with service bindings for in-process calls instead of public HTTP round-trips between them.
No observability is in place when the first incident hits.
Wire Workers logs/Logpush, tail consumers, error reporting, and analytics into the architecture before production traffic, not after.
Output
Useful deliverables
- Architecture decision record setting the native-rules-versus-Workers boundary.
- Route and execution map: hostnames, path patterns, execution position, and service-binding composition.
- Storage design selecting KV, D1, R2, and Durable Objects per data shape with rationale.
- Async and durable-execution design using Queues and Workflows with idempotency notes.
- Security model: input validation, auth, Wrangler secret bindings, and per-environment config.
- Observability plan: Workers logs/Logpush, tail consumers, error reporting, and analytics.
- CI/CD and rollback design with Wrangler preview, versioned, and gradual deployments.
Keep reading
Related resources
FAQ
Frequently asked questions
Common questions teams ask when putting this resource into practice.
When should a Cloudflare Worker be used instead of a native rule?
Use Transform, Cache, Redirect, and Origin Rules for header edits, redirects, routing, and cache decisions. Reach for a Worker only when the logic needs code — computation, external calls, state, or branching that declarative rules cannot express.
How do I choose between KV, D1, R2, and Durable Objects?
KV suits read-heavy, eventually consistent config and lookups; D1 suits relational queries; R2 suits objects and large blobs; Durable Objects suit per-key coordination and strong consistency. The data's shape and consistency needs drive the choice, not familiarity.
How should long-running or multi-step work be handled?
Keep request-path Workers fast and within CPU and subrequest budgets, and move buffered processing to Queues and durable multi-step processes to Workflows. Design consumers and steps to be idempotent because retries and at-least-once delivery are expected.
How do Workers call each other?
Use service bindings so one Worker invokes another in-process, avoiding public HTTP round-trips. This reduces latency and removes a network failure point compared with chaining Workers over HTTP.
How do I deploy and roll back a Workers application safely?
With Wrangler: develop against preview environments, ship versioned and gradual (percentage) deployments, and keep the prior version instantly deployable. Observability via Workers logs/Logpush and tail consumers should be in place before production traffic.
Nanosek
Design Workers architecture
Nanosek can turn this resource into a practical delivery plan for your environment — with rollback planning, stakeholder alignment, and 24/7 managed operations support.