URL Shortener Architecture: Inside Zippy's Redirect Engine

Zippy's URL shortener architecture has two moving parts: a Cloudflare Worker that runs the redirect logic and a KV store that holds every link. Because both are replicated across Cloudflare's 300+ edge locations, a tap resolves at the data center nearest the user — no origin server, no central database in the redirect path.

That's the whole answer. The rest of this guide unpacks why it's built that way, what actually happens between the tap and the native app opening, and why this architecture is the reason we can make promises other link tools can't — like links that never stop redirecting.

What happens when someone taps a Zippy link?

A tap on a zipthe.link URL hits the nearest Cloudflare edge location, where a Worker looks up the slug in KV, reads the user agent to detect the platform and OS, and returns the right escape route for that combination — all in a single edge round trip.

Step by step:

1. The request lands at the edge. Cloudflare terminates the connection at whichever of its 300+ cities is closest to the person tapping. Someone in Tel Aviv and someone in Toronto never touch the same machine.
2. The Worker reads the slug from KV. The link record — destination URL, platform targeting rules, active/read-only status — lives in Workers KV, a key-value store replicated globally. Hot links are served from a local cache at the same edge.
3. Platform + OS detection. The Worker inspects the user agent to answer two questions: which app is this tap coming from (Instagram, TikTok, LinkedIn, WhatsApp, Reddit, Product Hunt, YouTube, X), and is this iOS or Android?
4. The escape route is chosen. On iOS, the engine uses the destination platform's app URL scheme with a timed fallback to the web. On Android, it builds an intent:// URL, which carries a native fallback baked in. If a scheme is ever wrong or unsupported, the link degrades to opening the browser — never to a broken page.
5. Click recorded, user gone. Analytics are written out of band, so counting the click never delays the redirect.

If you want the full story on why the escape route matters — what actually happens to a click inside a webview — read why links die in the in-app browser.

Why Cloudflare Workers and KV instead of a server and a database?

Because a redirect is the one request you cannot afford to make slow or fragile, and the traditional shortener stack — a web server in one region querying a database — puts both a network hop and a single point of failure in front of every single click.

Here's the same tap through both architectures:

The honest trade-off: KV is eventually consistent. When you edit a link's destination (a Hero-plan "living link"), the change propagates to every edge within seconds rather than instantly. For a redirect engine that's the correct trade — reads outnumber writes by many thousands to one, and a click should never wait on a consensus protocol.

There's a second-order benefit, too. Workers + KV has effectively no marginal cost per redirect, which is why Hero plans have unlimited clicks, never metered. Architectures with a database in the hot path meter clicks because every click costs them a query. Ours don't, so we don't.

How does the redirect open the native app instead of the in-app browser?

The Worker doesn't return a plain 301 to the destination URL — it returns the platform-specific escape route that hands the tap to the operating system, which opens the installed native app instead of the in-app webview.

The mechanics differ by OS, and the engine handles both:

• iOS: app URL schemes with a timed fallback. The engine attempts the app; if nothing claims the tap within the window, it falls through to the web destination.
• Android: intent:// URLs, which declare the target app and a native fallback in one structure — the OS itself handles the "app not installed" case.
• The failure mode is boring on purpose. A wrong or deprecated scheme degrades to opening the browser. The worst case is the status quo; it is never a dead link.

Each destination platform has its own quirks in how it accepts these handoffs, which is exactly the routing table we maintain so you don't have to. For the per-platform specifics, see the Instagram deep links guide and the TikTok deep links guide.

Why does this architecture make the permanence promise possible?

Zippy's Permanence Law — links never stop redirecting, not on the free plan, not after a trial, not after you cancel — is enforceable because serving a redirect from KV at the edge costs effectively nothing, so there is no economic pressure to ever switch one off.

Concretely:

• A free Sidekick account holds 5 active links. Go over a plan's cap and the extra links flip to read-only: you can't edit them, but they keep their slug and keep redirecting.
• Cancel a paid plan and your links soft-downgrade. They do not die. There is no state in this system where a previously working slug returns a 404.
• The 14-day Hero trial ends the same way — features downgrade, redirects don't.

A shortener with a metered database in the hot path has to decide what happens when you stop paying, and the cheap answer is "the link dies." Our hot path is a cached key-value read; the cheap answer is the permanent answer.

Can you run the redirect engine yourselves?

Yes — the entire redirect engine is open source under the AGPL at github.com/zippylink/zippy, and it deploys to your own Cloudflare account as a Worker plus a KV namespace.

The same code that serves zipthe.link in production serves your self-hosted instance; there's no crippled community edition. The walkthrough lives in the self-hosting Zippy on Cloudflare guide, and the reasoning behind opening it up is in why Zippy is open source. The hosted cloud is the paid product: we run the infrastructure, maintain the platform routing table as apps change their behavior, and layer on the analytics, custom slugs, and the living-links editor.

FAQ

How fast is a Zippy redirect?

Fast enough that the redirect is never the bottleneck — the lookup is a key-value read served from the Cloudflare edge location nearest the user, with hot links cached locally at that edge. The slow part of any tap is the destination app launching, not the redirect resolving. There is no origin server round trip in the path.

What happens if the destination app isn't installed?

The link falls back to the web destination in the browser. On Android the fallback is declared natively inside the intent:// URL, so the OS handles it; on iOS the engine uses a timed fallback after attempting the app scheme. Either way the person lands on your destination — an uninstalled app never produces a dead end.

Does the KV architecture mean edited links update slowly?

Edits propagate to every edge location within seconds, not instantly — KV is eventually consistent by design. For "living links" (Hero plan) this means a destination swap is live worldwide moments after you save it. In exchange, every read is local and fast, which is the right trade for a system that serves thousands of reads per write.

Is the open-source version the real engine?

Yes. The AGPL repo on GitHub contains the actual redirect engine — Workers, KV schema, platform detection — not a demo. Self-hosting it on your own Cloudflare account is fully supported; paying for the hosted cloud gets you the maintained routing table, full analytics, and the dashboard on top.

Want the architecture without running it? Grab a Zippy link at zipthe.link — first tap opens the app, we promise.