Design TinyURL

Before drawing a single box, you need to agree on what the system actually does. This step is about compression — taking an ambiguous problem statement and narrowing it to a concrete, agreed-upon scope. The problem statement is deliberately left ambiguous. Your job is to ask the right questions and confirm the answers back.

The hardest part of requirements gathering for most people is knowing what to ask. The instinct is to ask about features — "can users edit their URLs?" — but the more important questions are about constraints: how many users? how fast must it be? what happens if it's down? Features define what the system does; constraints define how hard building it actually is.

A practical approach is to split requirements into two buckets and fill each one deliberately:

The most important call in this step is analytics. It sounds like a minor feature — but it determines the redirect type (302 vs 301), which determines whether you need a streaming pipeline at all, which is one of the most complex parts of the system. Getting this scope decision wrong early cascades through every subsequent step. This is why you surface it explicitly rather than assuming.

Personas help you define the use cases concretely — who uses the system, what they do, and what they care about. For some systems this step is critical (a social network has dozens of meaningful user types with very different access patterns). For a URL shortener, it's simpler.

Estimation isn't a math test — it's a reasoning signal. The numbers you produce here constrain every architectural decision that follows. Get this wrong and your design is built on fiction. The key is to work from what you know (DAU) to what you need (RPS, storage, cache size) in a chain of logical steps.

The API definition forces you to think from the consumer's perspective before drawing any internal boxes. Two endpoints cover the full functional scope from step 1A — one for creating a short URL, one for using it.

The GET endpoint is deliberately minimal. The client sends a short code and gets a redirect back. There's no response body to parse, no JSON to decode — just a status code and a Location header. This is intentional: the consumer of a short URL should get to their destination as fast as possible.

The system has two fundamentally different traffic patterns that need to be designed separately. Reads (redirects) are high-volume, latency-sensitive, and should almost never touch the database. Writes (URL creation) are lower-volume, slightly higher latency is acceptable, but must guarantee uniqueness. Mixing these concerns would produce a worse design for both.

The goal of the read path is to return the long URL as fast as possible. At 10,000 requests per second, every unnecessary database hit is a problem. The two-level cache exists specifically to absorb this load.

• L1 Local Cache check first — each web server has an in-process cache holding the hottest URLs. If a URL is going viral — say, a link tweeted by a celebrity getting 50,000 clicks per minute — that URL gets promoted to L1 on every web server. Requests are served entirely in-process, zero network hops. This is the fast path for the case that matters most.
• Redis Cache check — the shared L2 cache holds the broader set of recently active URLs. Most reads (~80-90%) hit here. The key is the shortCode, the value is the longUrl. A Redis lookup is a single network round-trip, typically sub-millisecond.
• DB lookup on miss — only cold URLs, rarely accessed URLs that have aged out of cache, reach the database. The shortCode column is indexed, so the lookup is fast. On the way back, the URL is populated into Redis and L1 so the next request doesn't hit the DB.
• Invalid code check — before any cache or DB lookup, validate that the shortCode looks like a valid 7-character Base62 string. This protects against bots probing random codes and generating useless DB load.
• Fire-and-forget analytics emit to Kafka — after the redirect is determined, emit a click event to Kafka. This is asynchronous — the 302 response goes back to the client immediately, without waiting for the Kafka write to complete. A lost event is acceptable; a slow redirect is not.

The write path has a harder problem: generating a unique code at 1,000 requests per second across multiple web servers without coordination overhead. The pre-generated pool solves this cleanly — the web server's job on a write is just to claim a code that's already been created, not to generate one on the fly.

• Duplicate URL check — first, check if this user has already shortened this exact URL. If yes, return the existing short code. This keeps the system idempotent: submitting the same URL twice gives the same result, which is what users expect. (Note: different users submitting the same URL get different codes — more on this in 5D.)
• Claim a code from the Code Pool table — the pre-generated pool always has 5,000–10,000 codes ready. The web server does an atomic delete-and-return: grab the next available code, remove it from the pool. No generation logic happens here. No uniqueness check against the URLs table. The code is guaranteed unique because the nanny service guaranteed it when creating the pool.
• Insert into URLs table — write the shortCode, longUrl, userId, and timestamps. The UNIQUE constraint on shortCode is a safety net, not the primary uniqueness mechanism.
• Return shortUrl to client — combine the base domain with the short code and return. The client can start using the link immediately.

The region prefix idea was tempting at first — if each web server generates codes with a region-specific prefix (US servers generate "us_xxxxx", EU servers generate "eu_xxxxx"), then codes are structurally unique with no coordination needed. But this approach was abandoned for two reasons: it consumes part of the 7-character code space on a prefix, reducing the combinatorial headroom from 62⁷ to 62⁵; and it doesn't handle custom aliases cleanly, since a user-specified alias has no region prefix by definition. Mixing the two approaches made the design inconsistent.

The pre-generated pool approach is cleaner. A background service generates codes ahead of time and stores them in a pool table. Web servers simply claim the next available code when a write comes in — no generation, no uniqueness check, no coordination. The entire code generation problem moves off the hot path.

The nanny service is a singleton background job. Its only responsibility is to keep the pool full. It does this by checking the pool size periodically and generating new codes whenever the pool drops below a threshold.

• Pool target: 10,000 codes — at 1,000 writes/sec, this is a 10-second buffer. Enough time for the nanny to detect a low pool and refill it even if it runs every few seconds.
• Refill threshold: 5,000 codes — when the pool drops below 5,000 (half capacity), the nanny starts generating. At 1,000 writes/sec, this gives ~5 seconds of runway even if the nanny takes a moment to respond. This buffer-within-a-buffer is deliberate — it means the system never comes close to running out of codes under normal conditions.
• Generation algorithm: generate a random 7-character string from the Base62 alphabet [a-zA-Z0-9]. At a pool size of 10,000 codes against a space of 3.5 trillion, the probability of a collision is so low it's effectively zero. But the unique constraint on the pool table catches it anyway.
• Unique constraint as safety net — the short_code column in the pool table has a DB-level unique constraint. If the nanny somehow generates a duplicate, the INSERT fails silently (ON CONFLICT DO NOTHING) and the nanny moves on. No crash, no retry storm. The safety net costs nothing and prevents a theoretical edge case from becoming a production incident.

Without reclamation, the system has a slow leak. At 1,000 writes/sec, codes are consumed permanently — shortened URLs that nobody ever clicks again still hold their codes. Over time, the usable code space shrinks. The reclamation service prevents this by returning dormant codes to the pool.

• The Data Warehouse detects inactivity — a batch job runs nightly, scanning last_accessed_at across all URLs. Any URL with zero clicks in the past 3 months is a candidate for reclamation. The Data Warehouse already has all this click data from the analytics pipeline — no additional data collection is needed.
• Soft delete first, not hard delete — when a URL is flagged inactive, it gets state = INACTIVE. The record is not deleted. This matters: if someone follows an old link, they get a clear "URL expired" page rather than a random redirect to someone else's content (which would happen if the code was immediately reassigned). It also preserves history for abuse investigations.
• One more month of grace period — after going INACTIVE, the URL waits one additional month before reclamation. This handles the case of a URL that had a traffic lull — a campaign that paused, a blog post that went quiet — without permanently losing the code. Only URLs that have been inactive for 4 months total get their codes reclaimed.
• Code re-enters the pool — the reclamation service sets state = DELETED and re-inserts the short code back into the code_pool table. From that point, the code is available for new URL assignments. The system is self-sustaining indefinitely.

Every time someone follows a short link, we chose 302 over 301 specifically so that request hits our servers. That request is a click event — it tells us who clicked, when, from where, and on what device. The analytics pipeline is how we capture that event without slowing down the redirect.

The core design constraint is simple: the redirect must be fast regardless of what happens to the analytics write. If the analytics system is slow or temporarily down, the redirect still completes in milliseconds. This is why the analytics write is fire-and-forget — we emit an event to Kafka and return the 302 response immediately. We don't wait to confirm the event was received or stored.

{
  "event_type": "url_click",
  "short_code": "abc1234",
  "long_url": "https://example.com/...",
  "user_id": "usr_xyz",           // null for anonymous
  "timestamp": "2026-08-16T14:23:11Z",
  "ip_address": "203.0.113.42",   // for geo analytics
  "user_agent": "Mozilla/5.0...", // device type
  "referrer": "https://twitter.com"
}

Analytics queries have two very different shapes, and no single storage system serves both well. Someone looking at a dashboard wants to know "how many clicks in the last hour?" — they need low-latency access to recent raw events. Someone running a monthly report wants "total clicks by country over the past 30 days" — they need pre-aggregated historical data, because scanning 30 days of raw events at 10K clicks/sec is billions of records. Lambda architecture handles both by using two separate layers.

The analytics API serves as the query router — it knows which layer to hit based on the time range of the query. Recent queries go to the speed layer, historical queries go to the batch layer. The user sees a single analytics dashboard; the two-layer complexity is hidden behind the API.

The database can handle reads — it's indexed on shortCode, lookups are fast. But at 10,000 reads per second, hitting the database for every redirect would saturate it quickly. A URL shortener's read pattern is also highly skewed: a small number of URLs get the vast majority of traffic. This makes caching extremely effective — you only need to cache the hot URLs to absorb most of the load.

The reason for two cache levels comes from a specific problem: viral URLs. When a link goes viral — a post shared by someone with millions of followers, a product launch announcement, a news story — that single URL might receive thousands of requests per second for a short window. Even Redis, shared across all web servers, becomes a bottleneck at that scale. The L1 local cache on each web server handles this by absorbing the viral URL's traffic entirely in-process.

L1 is small, fast, and selective. It doesn't hold all URLs — just the ultra-hot ones that would otherwise flood Redis with repeated requests for the same key.

• What goes in L1 — threshold-based promotion: A URL gets promoted to L1 when its request rate crosses a threshold — say, more than 100 requests per minute on a given web server. This is measured in the web server itself. Below the threshold, URLs are served from Redis. Above it, they live in L1 until traffic drops back down.
• Why threshold-based rather than just caching everything: If you promoted every URL to L1, you'd have thousands of entries per server consuming significant memory. L1 is valuable precisely because it's small and hot — fill it with cold URLs and you've wasted memory that could be used for JVM heap. Only viral URLs earn their spot in L1.
• Size: Small — 1,000 entries per server is plenty. If the top 1,000 URLs are in L1, those URLs account for a disproportionate fraction of total traffic. Everything else hits Redis.
• Eviction: LRU. A URL whose traffic drops below threshold ages out of L1 naturally. The next request for that URL misses L1 and goes to Redis — which is the right fallback.

Redis is the workhorse of the read path. It's shared across all web servers, so a URL cached in Redis is available to any server that handles that URL's traffic. The key insight for sizing is that URL traffic is highly skewed — you don't need to cache 35TB of URLs, just the active fraction.

• Size calculation: Assume 20% of all URLs account for the vast majority of traffic — these are "active" URLs (clicked at least once in the past 30 days). If there are ~50M URLs total, 20% = 10M active URLs × 100 bytes each = ~1GB. With Redis key overhead and headroom, budget 2GB. That's a single Redis instance — no sharding needed at this scale.
• Eviction policy — LRU: When Redis reaches capacity, evict the least recently used URL. Cold URLs that nobody has clicked in weeks naturally age out. Hot URLs that are clicked frequently stay in cache. This is the right eviction policy for a system where recency of access correlates strongly with future access.
• TTL — 30 days: Set a hard TTL of 30 days on every cache entry regardless of access frequency. This ensures that if a long URL is ever updated (even though we said URL editing is out of scope — a future feature), the cache doesn't serve stale data indefinitely. It also aligns with the reclamation service's inactivity threshold.
• Cache population on DB hit: When a request misses both L1 and Redis and hits the database, populate both Redis and L1 on the way back. The next request for that URL will hit L1 immediately — no additional network hops for the follow-up requests that often cluster around a newly-active URL.

Here's a question that seems simple but has a non-obvious answer: what happens when two different users submit the same long URL? Do they get the same short code, or different ones?

The instinct is to say "return the same short code" — it saves storage, it's efficient, same URL means same destination anyway. But this instinct is wrong when analytics is in scope. Here's why: if User A and User B both shorten the same URL and get the same short code, then every click on that short code is attributed to both of them. Their analytics are merged. You cannot tell how many of those 500 clicks came from User A's Instagram post versus User B's newsletter. The analytics data becomes meaningless for per-user attribution.

The same-user deduplication is a product expectation: if you shorten the same URL twice, you should get the same short link back. It would be confusing to get a different code. And since both clicks would be attributed to you anyway, there's no analytics reason to create a new code — just return the one you already have.

The different-user case is where the design decision is actually interesting. Sharing a code between users conflates their analytics — you'd see 502 total clicks but have no way to know 500 were from User A and 2 were from User B. Separate codes solve this completely. Each code maps to one owner; all clicks on that code are attributed to that owner.

The data model flows directly from the access patterns established in the design. The primary access pattern on the read path is: given a short_code, return a long_url. This is a pure key-value lookup — no joins, no range scans, no aggregations. That access pattern points toward a simple, indexed table where short_code is the primary key.

The write path adds two pieces of context: user_id (for same-user deduplication and analytics attribution) and state (for the soft-delete reclamation lifecycle). The data model is intentionally simple — complexity lives in the application logic, not the schema.