My Note

Cloudflare Architecture Examples with Mermaid Diagrams

March 21, 2026 • Category: development • Tags: cloudflare, architecture, mermaid, workers, pages, zero-trust, r2, d1, durable-objects, queues

A practical guide to common architecture patterns you can build with Cloudflare, including websites, APIs, Zero Trust access, media delivery, edge applications, event-driven systems, and SaaS platforms.

This guide is based on Cloudflare’s current official product and reference-architecture documentation as of 2026-03-21.

Table of Contents

  1. How to read these architectures
  2. Cloudflare building blocks
  3. Pattern 1: Proxying a traditional website through Cloudflare
  4. Pattern 2: Static site on Pages with dynamic APIs on Workers
  5. Pattern 3: Global API at the edge with Workers + KV
  6. Pattern 4: Stateful real-time app with Durable Objects
  7. Pattern 5: File uploads and user-generated content with R2
  8. Pattern 6: Image optimization pipeline with R2 + Image Resizing + cache
  9. Pattern 7: Event-driven background processing with Workers + Queues
  10. Pattern 8: Edge frontend + relational data with Workers/Pages + D1
  11. Pattern 9: Edge app with external database via Hyperdrive
  12. Pattern 10: Zero Trust access to private apps with Tunnel + Access
  13. Pattern 11: Secure Internet egress and SaaS protection with Zero Trust
  14. Pattern 12: Multi-tenant SaaS platform with Workers for Platforms
  15. Pattern 13: Hybrid origin protection with CDN + WAF + DDoS + Load Balancing
  16. Pattern 14: AI application at the edge with Workers AI + Vectorize + R2
  17. Pattern 15: SASE-style enterprise architecture
  18. How to choose the right data product
  19. Reference architectures by use case
  20. Common mistakes and anti-patterns
  21. A simple path to try Cloudflare quickly

How to read these architectures

Each pattern includes:

These are reference patterns, not rigid templates. Most production systems combine multiple patterns.

Cloudflare building blocks

Before the examples, it helps to group Cloudflare into a few architectural layers:

1) Edge network and application services

2) Developer platform

3) Zero Trust / SASE

4) Network services

A useful mental model is:

Pattern 1: Proxying a traditional website through Cloudflare

When to use it

You already have a website running on a VM, VPS, container platform, or traditional load balancer and want better performance and security without replatforming.

Why Cloudflare fits

This is the most common entry point: point your DNS at Cloudflare, proxy your public records, and let Cloudflare sit in front of the origin for caching, TLS termination, WAF, and DDoS protection.

Diagram

flowchart LR
    U[Users] --> CF[Cloudflare Edge\nDNS + CDN + TLS + WAF + DDoS]
    CF --> LB[Optional Cloudflare Load Balancing]
    LB --> O1[Origin Web Server A]
    LB --> O2[Origin Web Server B]
    O1 --> DB[(App Database)]
    O2 --> DB

Services involved

Strengths

Tradeoffs

Good fit

Pattern 2: Static site on Pages with dynamic APIs on Workers

When to use it

You want a JAMstack-style site or frontend app with dynamic APIs close to users.

Diagram

flowchart TB
    Dev[Developer / Git Push] --> Pages[Cloudflare Pages\nStatic frontend deployment]
    Users --> Edge[Cloudflare Edge]
    Edge --> Pages
    Edge --> WorkerAPI[Workers API]
    WorkerAPI --> KV[(KV / D1 / R2 / External APIs)]

Why this works well

Pages is ideal for deploying static assets and frontend frameworks, while Workers handles API routes, auth flows, feature flags, personalization, and backend integrations.

Strengths

Tradeoffs

Typical examples

Pattern 3: Global API at the edge with Workers + KV

When to use it

You need a globally distributed API with read-heavy access patterns: config, flags, routing rules, session-adjacent data, cached API lookups, or edge personalization.

Diagram

flowchart LR
    C[Clients] --> W[Cloudflare Workers API]
    W --> KV[(Workers KV)]
    W --> Cache[(Cloudflare Cache)]
    W --> Origin[Optional origin API]

Why Cloudflare fits

Workers runs code globally; KV provides globally distributed, low-latency reads and is particularly well suited for read-heavy workloads.

Strengths

Tradeoffs

Use this for

Avoid this for

Private machine-to-machine variant: Worker APIs with no anonymous access

This is the pattern to use when your Worker API is not for browsers or public clients. Instead, it should only be called by:

The design goal is simple:

The API should return 403 or be blocked unless the caller is an explicitly authenticated machine.

flowchart LR
    Ext[External backend programs\ncron / CI / trusted servers] -->|Access service token\nor mTLS| Edge[Cloudflare Edge]
    Anon[Anonymous Internet client] --> Edge
    Edge -->|Allowed machine traffic| Gateway[Public gateway Worker\napi.example.com]
    Edge -->|Deny anonymous traffic| Reject[403 / blocked]
    Gateway -->|Service Binding| InternalA[Internal Worker A\nno public route]
    Gateway -->|Service Binding| InternalB[Internal Worker B\nno public route]
    InternalA --> Data[(D1 / KV / R2 / external origin)]
    WorkerX[Another Worker in your account] -->|Service Binding| InternalA

Best default design

Use a two-layer model:

  1. One public entry Worker on a stable API hostname such as api.example.com.
  2. Several internal Worker services behind Service Bindings.

In this model:

This keeps your machine-facing edge small and avoids turning every Worker into a separately exposed public API.

Authentication choice by caller type

Caller Best default Why
Another Worker in the same Cloudflare account Service Bindings Private by design, no public URL, no shared secret in transit
External backend program that can send headers Cloudflare Access service token Designed for automated systems and service-to-service HTTP access
External backend or agent that can hold client certificates API Shield mTLS Strong machine identity at the TLS layer before the request reaches the Worker
Third-party sender that cannot use Access or mTLS App-level HMAC/JWT validation inside the Worker Fallback when you must control auth in application code

Worker-to-Worker inside Cloudflare: use Service Bindings first

If the caller is another Worker you control, do not call the target Worker over its public URL unless you truly need Internet-reachable behavior.

Service Bindings are the better default because they:

Minimal wrangler.toml example for the caller:

[[services]]
binding = "INTERNAL_API"
service = "internal-api-worker"

Then the caller can use the binding instead of a public hostname:

const response = await env.INTERNAL_API.fetch(
  new Request("https://internal/do-work", request)
);

External backend programs: put machine auth at the edge

If the caller lives outside Cloudflare, the strongest default is to require machine authentication before the request is treated as valid application traffic.

Option A: Cloudflare Access service tokens

This is a strong default for backend-to-backend HTTP calls.

Your external program sends:

CF-Access-Client-Id: <CLIENT_ID>
CF-Access-Client-Secret: <CLIENT_SECRET>

Cloudflare Access can evaluate that request with a Service Auth policy instead of an end-user login flow.

Practical notes:

Option B: API Shield mTLS

This is a strong choice when the external backend program or agent can safely hold a client certificate.

Use it when:

In practice, this is especially attractive for fixed backend programs, internal agents, or controlled partner integrations on a custom API hostname.

Option C: Application-level HMAC or JWT validation

Use this only when Access service tokens or mTLS are not a good fit.

If you choose app-level auth:

sequenceDiagram
    participant Job as External backend program
    participant Edge as Cloudflare Edge
    participant Auth as Access Service Auth or mTLS
    participant Gateway as Public gateway Worker
    participant Internal as Internal Worker via Service Binding

    Job->>Edge: HTTPS request with service token or client cert
    Edge->>Auth: Evaluate machine identity
    alt Authenticated machine
        Auth->>Gateway: Forward request
        Gateway->>Gateway: Validate JWT or signature
        Gateway->>Gateway: Check path, method, scope
        Gateway->>Internal: Service Binding fetch / RPC
        Internal-->>Gateway: Response
        Gateway-->>Job: 200 / 4xx / 5xx
    else Anonymous or invalid machine
        Auth-->>Job: 403 / blocked
    end

Concrete design rules

If you want the API to be usable only by your backend programs and other Workers:

Practical blueprint

The most maintainable version usually looks like this:

This gives you one externally reachable API edge and a set of private Worker services behind it.

Pattern 4: Stateful real-time app with Durable Objects

When to use it

You need coordination among many clients: chat rooms, collaborative editing, lobbies, counters, live presence, or shared state.

Diagram

flowchart LR
    U1[User 1] --> W[Worker Entry]
    U2[User 2] --> W
    U3[User 3] --> W
    W --> DO[Durable Object Instance\nSingle logical coordinator]
    DO --> S[(Durable Object Storage / SQLite-backed state)]

Why Cloudflare fits

Durable Objects combine compute and state in a single logical instance, making them useful for coordination-heavy systems.

Strengths

Tradeoffs

Examples

Pattern 5: File uploads and user-generated content with R2

When to use it

You need scalable object storage for uploads, documents, images, logs, model outputs, or downloadable artifacts.

Diagram

sequenceDiagram
    participant User
    participant App as Worker/API
    participant R2 as Cloudflare R2

    User->>App: Request upload permission
    App->>R2: Generate signed URL / policy
    App-->>User: Return upload URL
    User->>R2: Upload file directly
    R2-->>App: Optional event / metadata workflow

Why Cloudflare fits

R2 is Cloudflare’s S3-compatible object storage and is designed for storing and serving unstructured data without egress fees.

Strengths

Tradeoffs

Good pattern

Store the binary in R2, and store metadata/ownership in D1, Durable Objects, or an external SQL database.

Pattern 6: Image optimization pipeline with R2 + Image Resizing + cache

When to use it

You serve many images and want a fast, scalable way to store originals once and deliver optimized variants on demand.

Diagram

flowchart LR
    Editor[Content uploader] --> R2[(Original images in R2)]
    User[End user browser] --> CF[Cloudflare Edge]
    CF --> Resize[Image Resizing / Transformation]
    Resize --> R2
    Resize --> Cache[(Edge cache of transformed variants)]
    Cache --> User

Why Cloudflare fits

Cloudflare’s reference architectures explicitly highlight image delivery and image-resizing patterns with R2 and cache.

Strengths

Tradeoffs

Great for

Pattern 7: Event-driven background processing with Workers + Queues

When to use it

A request should return quickly, but heavy work should happen asynchronously: email, indexing, thumbnails, notifications, ETL, retryable jobs.

Diagram

flowchart LR
    Client --> API[Worker API]
    API --> Q[Cloudflare Queues]
    API --> FastResp[Immediate response]
    Q --> Consumer[Queue consumer Worker]
    Consumer --> R2[(R2)]
    Consumer --> D1[(D1)]
    Consumer --> SaaS[Email / Webhook / 3rd-party API]

Why Cloudflare fits

Queues integrates with Workers and is designed for guaranteed-delivery-style messaging, offloading work from request/response flows.

Strengths

Tradeoffs

Examples

Pattern 8: Edge frontend + relational data with Workers/Pages + D1

When to use it

You want a simple full-stack app on Cloudflare and your workload is relational: users, posts, products, tasks, comments, admin dashboards.

Diagram

flowchart TB
    Users --> App[Pages / Worker app]
    App --> Auth[Auth logic]
    App --> D1[(Cloudflare D1)]
    App --> R2[(Optional file storage in R2)]
    App --> KV[(Optional config/cache in KV)]

Why Cloudflare fits

This is the easiest all-Cloudflare full-stack pattern for many small to mid-size applications.

Strengths

Tradeoffs

Good for

Pattern 9: Edge app with external database via Hyperdrive

When to use it

You want Workers at the edge, but your system of record stays in an existing PostgreSQL or MySQL database.

Diagram

flowchart LR
    Users --> W[Cloudflare Worker]
    W --> H[Hyperdrive]
    H --> DB[(Existing Postgres/MySQL)]
    W --> KV[(Optional KV cache)]
    W --> R2[(Optional R2 objects)]

Why Cloudflare fits

Hyperdrive is designed to accelerate database access from Workers to existing databases, making hybrid architectures practical.

Strengths

Tradeoffs

Best for

Pattern 10: Zero Trust access to private apps with Tunnel + Access

When to use it

You want users to reach private web apps, SSH, RDP, APIs, or dashboards without opening inbound firewall ports and without relying on a broad VPN.

Diagram

flowchart LR
    User[User with browser or client] --> Access[Cloudflare Access]
    Access --> CF[Cloudflare Edge]
    PrivateHost[Private app / server]
    PrivateHost --> Tunnel[cloudflared Tunnel\noutbound-only connection]
    Tunnel --> CF

Why Cloudflare fits

Cloudflare Tunnel publishes internal services using outbound-only connections from cloudflared, while Access enforces identity-aware policies in front of the application.

Strengths

Tradeoffs

Great for

Pattern 11: Secure Internet egress and SaaS protection with Zero Trust

When to use it

You want to secure employee access to the public Internet and SaaS apps with policy enforcement, DNS/HTTP filtering, and identity-aware controls.

Diagram

flowchart LR
    Device[Managed user device] --> WARP[WARP client]
    WARP --> Gateway[Cloudflare Gateway / SWG]
    Gateway --> SaaS[SaaS apps]
    Gateway --> Internet[Public Internet]
    IdP[Identity Provider] --> AccessPolicy[Identity & posture policy]
    AccessPolicy --> Gateway

Why Cloudflare fits

This maps to Cloudflare’s Zero Trust / SASE model: route traffic through Cloudflare, apply policy, and protect access to SaaS and the Internet.

Strengths

Tradeoffs

Good fit

Pattern 12: Multi-tenant SaaS platform with Workers for Platforms

When to use it

You are building a platform where customers bring custom code, custom routes, per-tenant apps, or programmable extensions.

Diagram

flowchart TB
    EndUser[End users] --> Edge[Cloudflare Edge]
    Edge --> Host[Your platform control Worker]
    Host --> TenantA[Tenant Worker A]
    Host --> TenantB[Tenant Worker B]
    Host --> TenantC[Tenant Worker C]
    Host --> Control[(Control plane metadata / billing / auth)]

Why Cloudflare fits

Cloudflare’s programmable-platform reference architecture highlights Workers for Platforms as a foundation for multi-tenant SaaS with isolation and global distribution.

Strengths

Tradeoffs

Typical uses

Pattern 13: Hybrid origin protection with CDN + WAF + DDoS + Load Balancing

When to use it

You run multiple origins across regions or clouds and need availability, failover, and application-layer protection.

Diagram

flowchart LR
    Users --> CF[Cloudflare Edge\nCDN + WAF + DDoS + Rate Limiting]
    CF --> GLB[Cloudflare Load Balancing]
    GLB --> AWS[Origin in AWS]
    GLB --> GCP[Origin in GCP]
    GLB --> DC[Origin in Data Center]

Strengths

Tradeoffs

Best for

Pattern 14: AI application at the edge with Workers AI + Vectorize + R2

When to use it

You want an AI-backed application on Cloudflare: chat, semantic search, retrieval-augmented generation (RAG), classification, image generation, or document workflows.

Diagram

flowchart TB
    User --> App[Worker / Pages app]
    App --> AI[Workers AI]
    App --> V[(Vectorize)]
    App --> R2[(R2 document store)]
    App --> D1[(D1 app metadata)]
    Ingest[Ingestion Worker] --> R2
    Ingest --> Embed[Embedding generation]
    Embed --> V

Why Cloudflare fits

Cloudflare’s reference architectures now include AI solution patterns, and the platform combines edge app logic, storage, and AI inference primitives.

Strengths

Tradeoffs

Examples

Pattern 15: SASE-style enterprise architecture

When to use it

You want to evolve from perimeter/VPN-centric security toward identity- and policy-driven access across users, branches, SaaS, Internet, and private apps.

Diagram

flowchart TB
    User[Users on laptops / mobile] --> WARP[WARP client]
    Branch[Branch office / network on-ramp] --> CloudflareOne[Cloudflare One / Edge]
    User --> CloudflareOne
    CloudflareOne --> Gateway[Gateway / SWG]
    CloudflareOne --> Access[Access / ZTNA]
    CloudflareOne --> SaaS[SaaS apps]
    CloudflareOne --> Internet[Public Internet]
    CloudflareOne --> Tunnel[Cloudflare Tunnel]
    Tunnel --> PrivateApps[Private apps / data center / cloud VPC]
    IdP[Identity Provider]
    UEM[Device posture / UEM]
    IdP --> Access
    UEM --> Access
    IdP --> Gateway
    UEM --> Gateway

Why Cloudflare fits

Cloudflare’s recent SASE reference architecture shows a request path that starts from the user/device/browser and continues through Cloudflare to private apps or the public Internet.

Strengths

Tradeoffs

How to choose the right data product

Cloudflare explicitly documents storage selection as a multi-product decision. A practical rule of thumb:

Need Usually start with Notes
Global config / flags / read-heavy lookup KV Great for read-heavy workloads
Coordination / per-entity state / live sessions Durable Objects Best when one logical coordinator is needed
Relational app data D1 Good for many CRUD and app backends
Large files / media / exports / artifacts R2 Object storage
Existing external SQL Hyperdrive Good for hybrid migration
Async messaging / work offload Queues Pair with Worker consumers
Semantic retrieval Vectorize Pair with embeddings and metadata stores

A strong Cloudflare architecture often uses multiple data products together:

Reference architectures by use case

Small company website

SaaS MVP

Global realtime product

Enterprise internal tools

Existing enterprise app modernization

Common mistakes and anti-patterns

1) Using one product for everything

Do not try to force every problem into KV, D1, Durable Objects, or R2. They solve different problems.

2) Treating KV as a transactional database

KV shines for read-heavy distributed lookup workloads, not for strict transactional correctness.

3) Using Durable Objects without partition strategy

A bad object-key design creates hot spots. Model coordination scope explicitly.

4) Uploading files through your app server unnecessarily

For user uploads, prefer direct-to-R2 or signed upload patterns when feasible.

5) Forgetting origin hardening

Even behind Cloudflare, protect origins with allowlists, authenticated origin pulls, origin certificates, or private connectivity patterns where appropriate.

6) Rebuilding a VPN instead of using app-level access

For many internal tools, Access + Tunnel is simpler and safer than broad network-level access.

7) Ignoring cache design

Cloudflare’s value often depends on cache keys, cache eligibility, headers, image strategy, and static-vs-dynamic separation.

8) Exposing machine-only Worker APIs anonymously

If the endpoint is only meant for backend programs or other Workers, do not leave it as a public anonymous HTTP endpoint.

Prefer:

Only fall back to app-level shared-secret verification when the caller cannot use the stronger patterns.

A simple path to try Cloudflare quickly

If you want to try Cloudflare with minimal setup, choose one of these:

Option A: Put an existing site behind Cloudflare

  1. Add your domain to Cloudflare.
  2. Move authoritative DNS to Cloudflare.
  3. Proxy your public HTTP/S records.
  4. Enable TLS, cache basics, and WAF rules.
  5. Measure origin offload and page performance.

Option B: Deploy a static site with Pages

  1. Connect a Git repository.
  2. Deploy a static site or frontend framework.
  3. Add a Worker for one dynamic route.
  4. Optionally add KV or D1.

Option C: Publish one internal service with Tunnel + Access

  1. Install cloudflared.
  2. Create a Tunnel from your private host.
  3. Publish one hostname.
  4. Protect it with Access and your identity provider.

Option D: Build a tiny API with Workers

  1. Create a Worker.
  2. Add one route.
  3. Use KV for config or D1 for relational state.
  4. Add Queues if anything becomes asynchronous.

Notes on product fit

Source basis

This guide is grounded in Cloudflare’s official docs and reference architectures, especially the current pages for:

Final advice

Do not start by asking, “Which Cloudflare product should I use?”

Start by asking:

  1. Where should this request terminate? Edge, private service, or origin?
  2. What kind of state does this workload need? Object, relational, read-heavy lookup, or coordinated state?
  3. What needs to be synchronous, and what can be queued?
  4. Is this public traffic, private access, or user Internet egress?
  5. Can I solve this incrementally instead of replatforming everything?

That mindset usually leads you to the right Cloudflare architecture much faster.