Edge-First Architecture

Learning Focus

By the end of this lesson you will understand the "Edge-First" mental model, how to choose the right storage for your application, and how to design for global distribution.

The Edge-First Mental Model

In traditional architecture, your logic and database live in a single region (e.g., us-east-1). In Edge-First Architecture, your code and data live everywhere.

Feature	Traditional App	Edge-First App
Deployment	Single region (US, EU, or Asia)	Global (330+ cities)
Latency	200ms+ (global avg)	<20ms (global avg)
Scalability	Vertical/Horizontal scaling servers	Automatic (serverless)
Data	Central SQL database	Distributed (D1, KV, R2)

flowchart TD
    subgraph Traditional["Traditional (Single Region)"]
        T_USER["User (Global)"] --> T_LB["Load Balancer"]
        T_LB --> T_SRV["App Server (US)"]
        T_SRV --> T_DB["Database (US)"]
    end

    subgraph Edge["Edge-First (Global)"]
        E_USER["User (Global)"] --> E_W["Worker (Local Edge)"]
        E_W --> E_DB["D1 / KV / R2 (Edge Storage)"]
    end

    style T_SRV fill:#dc2626,color:#fff,stroke:#b91c1c
    style E_W fill:#16a34a,color:#fff,stroke:#15803d

Choosing the Right Storage

Designing for the edge means choosing the right storage for your data's consistency and access patterns.

Need	Storage Service	Best For
Relational Data	D1 Database	Blogs, CMS, User metadata, SQL apps
Simple Key-Value	Workers KV	Feature flags, configuration, long-lived sessions
Large Files	R2 Storage	Images, videos, backups, logs
Strict Consistency	Durable Objects	Real-time chat, counters, collaboration
Asynchronous Work	Queues	Log processing, email sending, retries

Example Architecture: SaaS Blog Platform

flowchart TD
    USER["Reader"] --> PAGES["Cloudflare Pages\n(Frontend)"]
    PAGES --> FUNCTIONS["Pages Functions\n(API logic)"]
    FUNCTIONS --> D1["D1 Database\n(Posts, Comments)"]
    FUNCTIONS --> R2["R2 Storage\n(Uploaded Images)"]
    FUNCTIONS --> KV["KV Store\n(Settings, Banned IPs)"]

    ADMIN["Admin"] --> FUNCTIONS
    
    style PAGES fill:#2563eb,color:#fff,stroke:#1e40af
    style D1 fill:#7c3aed,color:#fff,stroke:#6d28d9

Anti-Patterns to Avoid

• Backhauling Data: Don't put your Worker on the edge but connect to a database in a single region (like RDS in AWS us-east-1). This defeats the performance gains of the edge. Use D1 or KV instead.
• Large State in Memory: Workers are ephemeral. Don't store important data in local variables; it will disappear when the isolate is reclaimed. Use Durable Objects for state.
• Heavy CPU Work: Workers are CPU-limited (10ms free). Don't perform heavy video transcoding or complex PDF generation in a Worker. Offload to a background service via Queues.

Key Takeaways

• Edge-First means deploying logic and data globally by default.
• Minimize latency by keeping data close to workers.
• Match the storage service (D1, KV, R2) to your data's consistency requirements.
• Avoid backhauling to centralized databases — use Cloudflare's serverless storage.
• Design for ephemeral execution — use persistent storage for any state.

What's Next

• Continue to Troubleshooting and Monitoring to learn how to debug your edge applications.