Build a CDN
13 scenes · ~91 min · build the primitive

Build your own CDN

A globally-distributed reverse proxy whose only job is to (a) terminate the user's TCP/TLS milliseconds away and (b) serve a cached origin response so origin never sees the request. Internalize edge caching, anycast, TTL, revalidation, SWR, purge, the Vary footgun, origin shield, bypass, and hit ratio — and the dozen ways to misconfigure each.

Scenes
13 interactive scenes
Time
about 91 minutes
Topic
Caching, Proxies & the Edge

What you are building, and why

You set Cache-Control: max-age=3600 on your responses, put a static asset behind cdn.example.com once, and watched it serve fast. Then someone asked "why is our hit ratio 30%?" and "why are users still seeing the old version 8 minutes after we deployed?" and you realized you had no mental model for what the CDN actually does between the user's browser and your origin.

This curriculum builds that mental model from scratch, in the order a single HTTP request actually flows: browser → DNS → anycast → POP → cache lookup → (origin shield) → origin. Every concept is introduced in the scene where it first becomes load-bearing — TTL only after edge caches exist, revalidation only after staleness is a state, SWR only after the user-visible wait at the TTL boundary is felt, purge only after SWR ships you a bug, and the Vary footgun only after purge invalidates entries that the cache key has already shattered into a thousand variants.

Resist the urge to "describe a CDN." Make decisions yourself, defend them, and let the AI push back. The point is to build the dial-by-dial intuition that lets you debug a real production hit-ratio collapse — not to recite Cloudflare's product page.

What you will be able to explain afterwards

  • edge caching (hit / miss)
  • POPs and anycast routing
  • TTL via Cache-Control (max-age / s-maxage)
  • ETag-based conditional GET / 304
  • stale-while-revalidate / stale-if-error
  • URL / surrogate-key / zone-wide purge
  • cache key + Vary header cardinality
  • origin shield and thundering herd
  • bypass / pass-through for dynamic routes
  • hit ratio and the diagnostic ladder
  1. 00
  2. 01
  3. 02
  4. 03
  5. 04
  6. 05
  7. 06
  8. 07
  9. 08
  10. 09
  11. 10
  12. 11
  13. 12

Edge basics

The request journey, origin pain, an edge near each user, POPs and anycast.

  1. 00
    Foundations — the journey a request takes, and the words you'll hear — anycast routing to the nearest POP
    The whole request path on one diagram — browser → DNS → anycast → POP (the edge cache) → origin — plus a clickable glossary of the core journey terms. Orientation before you touch anything.
    ~7 min
  2. 01
    Without a CDN, every user crosses the planet
    One origin, three continents, and the cost: every user pays full cross-ocean RTT and origin RPS scales with your user count.
    ~7 min
  3. 02
    An edge near the user — hit and miss — per-region caching that cuts origin RPS
    An edge cache absorbs the second request in each region; the first still pays the full RTT, and edges don't share content across regions.
    ~7 min
  4. 03
    POPs and anycast — one IP, many doors
    Every POP advertises the same IP; the network's BGP routing fabric, not a CDN dispatcher, picks which edge each user reaches.
    ~7 min

Freshness

TTL, revalidation, stale-while-revalidate.

  1. 04
    TTL — origin tells the edge how long to trust the copy
    max-age applies to every cache, including the browser; s-maxage overrides it for shared caches like the CDN — and TTL is what flips a cell from fresh to stale.
    ~7 min
  2. 05
    Revalidation — the cheap question with the expensive wait
    When stale, the edge sends a conditional GET with the ETag; origin replies 304 Not Modified — body is empty, but the round trip isn't.
    ~7 min
  3. 06
    Stale-while-revalidate — and the bug it ships
    SWR removes the user-visible TTL-boundary wait by serving stale and refreshing in background — and extends any cached bug for the SWR window after deploy.
    ~7 min

Control

Purge flavors, the cache key, and the Vary footgun.

  1. 07
    Purge — URL, surrogate key, or sledgehammer
    Three purge flavors: URL (precise, slow at scale), surrogate-key (atomic, fast), zone-wide (sledgehammer that stampedes origin).
    ~7 min
  2. 08
    Cache key and Vary — when 'same URL' isn't
    The cache key defaults to method + URL; Vary multiplies it by request-header values — Vary: User-Agent shatters one URL into thousands.
    ~7 min

Operating

Shield, bypass routes, and the hit-ratio dashboard.

  1. 09
    Origin shield — collapsing the herd
    Without a shield, every POP independently misses on TTL expiry and stampedes origin in parallel; with a shield, origin sees one request instead of N.
    ~7 min
  2. 10
    Bypass — when caching is wrong, the CDN still earns its keep
    Auth and per-user routes must bypass the cache, and the CDN still pays for itself there: TLS termination at the POP, anycast routing, DDoS absorption.
    ~7 min
  3. 11
    Hit ratio — the headline and the diagnostic ladder
    Request hit ratio vs byte hit ratio, and the 5-step ladder when it crashes: Vary cardinality → TTL config → purge frequency → bypass rules → cookie key.
    ~7 min

Design

Workload-driven CDN configuration.

  1. 12
    Design your CDN configuration
    Capstone: pick TTL, Vary, purge strategy, shield, and bypass for static / authenticated API / video / real-time workloads — verifier traces every choice back to a scene.
    ~7 min

Where you'll use this

Product designs whose trade-offs turn on what this curriculum teaches.

More in Caching, Proxies & the Edge

Everything between the client and the origin: in-memory caches, CDNs, load balancers and service proxies — and the three ways a cache betrays you.

Prefer to design it yourself?

The same subject as a staged workspace: draw the architecture, and a simulator traces requests through the boxes you drew.

Open the Build a CDN workspace