Requirements

Functional Requirements:

• Create a short URL for a given long URL.
• Return the long URL associated with a given short URL.

Non-Functional Requirements:

List the key non-functional requirements (eg low latency, scalability, reliability, etc.)...

API Design

Write Path — Creating a Short URL

1. Client sends POST /api/v1/urls with the long URL
2. API Gateway authenticates and rate-limits the request
3. Write Service calls KGS via gRPC to atomically acquire a unique short key
4. Write Service persists the mapping to PostgreSQL primary
5. Write Service warms Redis cache (async, best-effort)
6. Short URL is returned to the client

Endpoint:

Other write endpoints:

Read Path — Redirecting a Short URL

1. Client hits GET /{short_key} (e.g., clicking a link)
2. CDN checks edge cache — if hit, returns 302 immediately (< 5ms, no backend hit)
3. On cache miss, request reaches Redirect Service
4. Redirect Service checks Redis — hit returns 302 in < 2ms
5. On Redis miss, falls back to PostgreSQL read replica, then populates Redis
6. url.clicked event is published to Kafka asynchronously (non-blocking)

Endpoint:

301 vs 302 decision: | | 301 Permanent | 302 Temporary | |-|--------------|---------------| | Browser caches redirect | Yes — no future server hit | No — every click hits server | | Click analytics possible | No | Yes | | CDN cache TTL | Long (days) | Short (minutes) | | Use when | No analytics needed, max caching | Analytics required (chosen) |

Internal API — Key Generation Service (gRPC)

Called only by URL Write Service. Not exposed externally.

High-Level Design

URL Write Service

Redirect Service

• Resolve short key
• cache-first lookup

Key Generation Service (KGS)

• pre-generate base62
• atomic keypoo;l

Analytics Service

• track click events
• stats per short url

Detailed Component Design

URL Write Service

Handles all mutations: creating short URLs, updating TTL, deleting. Separated from the read path because write traffic (~500 QPS) has fundamentally different characteristics — it requires ACID guarantees, calls KGS for a key, and writes to the primary DB. Bundling this with redirect logic would force the redirect path (50k QPS, p99 < 10ms) to share resources with slower, heavier write operations.

Redirect Service

The hottest path in the system. Every short link click hits this service. It is intentionally kept minimal — one job: look up short_key → long_url and return a 302. Separating it means we can scale it independently (10-100 pods), optimize it aggressively (Redis-first, no write DB connection pool), and ensure a Redis slowdown on the write side never bleeds into redirect latency.

Key Generation Service (KGS)

Solves the uniqueness problem without putting the burden on the write hot path. If the Write Service generated keys itself (e.g., hash or counter), every write would need a uniqueness check against the DB — a round-trip that adds latency and creates contention at scale. KGS pre-generates keys in bulk and hands them out atomically via gRPC, so a write just pops a ready key in < 1ms with zero collision risk.

Analytics Service

Click tracking is not on the critical path — a user doesn't wait for analytics before being redirected. Decoupling it via Kafka means: (1) a slow analytics query never blocks a redirect, (2) the analytics workload (aggregation, storage writes to Cassandra) can scale independently, and (3) if the analytics service goes down, redirects still work — we just buffer events in Kafka until it recovers.