shrt.design

Before the diagrams

Requirements & Data Flow

What the system has to do, what it has to be, and the sequence of steps that connects the two — written down once so every subsystem in this guide can be judged against the same bar.

Functional Requirements

Core Requirements

  • Users can submit a long URL and receive a short code that maps to it.
  • Visiting the short link redirects the browser to the original long URL.
  • Users can view click analytics for a link they created.

Below the line (out of scope)

  • Link previews / OG metadata scraping — a content-fetching concern, not a redirect problem.
  • QR code generation — a client-side rendering feature bolted onto an existing short code.
  • Team workspaces, permissions & billing — an orthogonal auth and monetization system.
  • Malicious URL / phishing detection at scale — worth naming as real, but a follow-up, not a first pass.

Non-Functional Requirements

Before locking in non-functional requirements, it's worth sizing the system out loud, because scale is what decides the caching strategy here. Say there are 10 million new short links created per day — about 115 writes/sec on average. But redirects are the real number: if each link gets clicked 20 times on average over its life, that's 200 million redirects/day, roughly 2,300 QPS average and several times that at peak, concentrated on whichever links are currently popular. The ratio — redirects dwarfing creations by 100:1 or more — is what justifies caching before anything else.

Core Requirements

  • Redirect latency is the product — every extra millisecond on the read path is felt directly by the end user.
  • Highly available redirect path — an outage here breaks every link that depends on it, everywhere it's been shared.
  • Generated short codes must be unique, with no collisions.
  • Read-heavy caching strategy that reflects the redirect:creation ratio, not an even split.
  • Click counts may be eventually consistent — a few seconds of replication lag is acceptable.

Below the line (out of scope)

  • Strong consistency on click counts.
  • Guaranteed permanent availability of every link with no expiration policy.
  • Global sub-50ms redirects from every edge location on day one.

Data Flow

  1. A user submits a long URL to be shortened.
  2. The key generation service allocates a unique short code, and the mapping is stored durably.
  3. The short link is returned to the user.
  4. A visitor requests the short link.
  5. The redirection service looks up the mapping (cache first) and issues an HTTP redirect, recording the click asynchronously.

High-Level Design

With requirements set, sketch the minimal set of components that satisfy them, wired directly to the endpoints above — not a generic "backend" box.

ClientLoad BalancerShorteningServiceKey GenerationServiceMapping DBRedirectionServiceCacheAnalyticsQueueClick Store

Click a component to see its role in this flow.

1. Shortening a URL — POST /api/shorten

Client → Load Balancer → Shortening Service → Key Generation Service allocates a unique short code, which is written to the Mapping DB; the short link is returned to the client. URL Shortening & Encoding → Key Generation Service →

2. Redirecting — GET /{code}

Client → Load Balancer → Redirection Service checks the Cache first; on a miss it falls back to the Mapping DB, issues an HTTP redirect immediately, and asynchronously publishes a click event to an Analytics Queue so the hot redirect path never blocks on a write. Redirection (Read Path) →

3. Viewing Click Analytics — GET /api/links/{code}

The Link Management Service reads aggregated click data — built from the async analytics stream, not the hot redirect path — and returns it to the link's owner. Link Management & Click Tracking →