board "URL shortener: system design" # 1. What it must do section "Requirements" track=requirements step=1 text "Functional" note "Shorten a long URL to a short, unique code" color=Green note "Redirect a short code to its long URL" color=Green note "Custom alias and expiry, both optional" color=Green text "Non-functional" note "Redirects: highly available, p99 < 50 ms" color=Blue note "Codes are not guessable in sequence" color=Blue note "Read heavy: 100 redirects per new link" color=Blue # 2. How big it gets section "Estimates" track=estimates step=2 note "Writes\n100M links / month\n≈ 40 / s (peak 400 / s)" note "Reads (100:1)\n≈ 4,000 / s (peak 40k / s)" note "Storage, 5 years\n6B links × 500 B ≈ 3 TB" color=Blue note "Cache: hot 20% of a day's reads\n≈ 35 GB of RAM" color=Teal note "Code length\n62^7 ≈ 3.5 trillion: 7 chars is plenty" color=Green # 3. The API: a card per endpoint. Click ▶ (or select it and press →) for its status, headers, req and res section "API" track=api step=3 ```http as api_create # Create a short link POST /api/v1/links Authorization: Bearer Content-Type: application/json { "url": "https://example.com/a/very/long/page", "alias": "promo", "expiresAt": "2027-01-01" } HTTP/1.1 201 Created Location: https://sho.rt/promo { "code": "promo", "shortUrl": "https://sho.rt/promo" } ``` ```http as api_get # Redirect GET /{code} HTTP/1.1 302 Found Location: https://example.com/a/very/long/page ``` ```http as api_stats # Click stats for a link GET /api/v1/links/{code}/stats Authorization: Bearer HTTP/1.1 200 OK Content-Type: application/json { "clicks": 1342, "byCountry": { "IN": 801, "US": 312 }, "byDay": [ { "day": "2026-11-13", "clicks": 96 } ] } ``` api DELETE /api/v1/links/{code} "Delete a link (owner only)" status=204 as api_delete note "Every write needs an API key; rate limited per key. 409 when an alias is taken, 404 for unknown or expired codes" color=Orange # 4. High-level design: the architecture section "High-level design" track=system step=4 ```mermaid flowchart LR subgraph Clients User[Browser / mobile app] end subgraph Edge DNS[DNS + CDN] LB[Load balancer] end subgraph App[Application tier] Write[Shorten service] Read[Redirect service] end subgraph Keys[Key generation] KGS[Key generation service] KeyDB[(Key DB: unused / used)] end subgraph Storage Cache[(Redis cache)] DB[(Links DB: Cassandra)] end subgraph Async[Background] Queue[[Kafka: click events]] Stats[Analytics workers] OLAP[(ClickHouse)] Sweeper[Expiry cleanup] end User --> DNS --> LB LB --> Write LB --> Read Write --> KGS --> KeyDB Write --> DB Read --> Cache Read --> DB Read --> Queue --> Stats --> OLAP Sweeper --> DB ``` # 5. Request paths, step by step section "Create a short link" track=system step=5 ```mermaid sequenceDiagram participant U as Client participant S as Shorten service participant K as Key generation service participant D as Links DB participant R as Redis U->>S: POST /api/v1/links { url } S->>S: validate URL, check API key quota S->>K: next key K-->>S: "aZ3kP9q" (from a pre-loaded batch) S->>D: INSERT code, url, owner, expiresAt S->>R: SET code → url (warm the cache) S-->>U: 201 https://sho.rt/aZ3kP9q ``` section "Redirect" track=system step=6 ```mermaid sequenceDiagram participant U as Client participant G as Redirect service participant R as Redis participant D as Links DB participant Q as Kafka U->>G: GET /aZ3kP9q G->>R: GET aZ3kP9q alt cache hit R-->>G: long URL else cache miss G->>D: SELECT url WHERE code = aZ3kP9q D-->>G: long URL (or not found) G->>R: SET aZ3kP9q (TTL 24h) end G-)Q: click event (async) G-->>U: 302 Location: long URL ``` # 6. Data model section "Data model" track=data step=7 ```mermaid erDiagram USER ||--o{ LINK : creates LINK ||--o{ CLICK : receives USER { string user_id PK string email string api_key datetime created_at } LINK { string code PK "7 chars, base62" string long_url string user_id FK datetime created_at datetime expires_at } CLICK { string code FK datetime at string country string referrer } ``` note "Key-value access only (code → URL), billions of rows: a NoSQL store like Cassandra or DynamoDB" color=Teal # 7. The hard parts section "Deep dive" track=deepdive step=8 ```mermaid flowchart TB subgraph KGS[Key generation service] Gen[Generate random base62 keys offline] --> Unused[(Unused keys)] Unused -->|load 1,000 at a time| Mem[Keys in memory] Mem -->|hand out one per request| Used[(Used keys)] end ``` note "Why a key service: no collisions and no DB lookup on create. Hashing the URL (MD5 → base62) needs collision checks." color=Blue note "Partitioning: hash(code) spreads keys evenly; range-based by first letter makes hot shards" color=Blue note "Cache: LRU, read-through; 20% of links take 80% of traffic. Cache 'not found' too, to stop scans" color=Teal note "KGS is a single point of failure: run a standby replica; a crash loses only the keys in memory" color=Red note "Expiry: delete lazily on read, plus a nightly sweep; expired keys go back to the pool" color=Grey # 8. Choices made section "Trade-offs" track=tradeoffs step=9 note "302 not 301: every click reaches us, so analytics count it, at the cost of more traffic" note "Clicks go through Kafka: a redirect never waits for analytics; numbers lag about a minute" note "Pre-generated keys vs hashing: simpler, faster writes, but KGS must be highly available" # Flows over the architecture: pick one in Sections → Flows to light up its path flow "Create a short link": User -> LB "POST /api/v1/links" -> Write -> KGS "next key" + DB "insert" flow "Redirect": User -> DNS "GET /{code}" -> LB -> Read -> Cache "hit?" -> DB "on a miss" flow "Count a click": Read -> Queue "click event" -> Stats -> OLAP flow "Expire old links": Sweeper -> DB "delete expired" connect api_create -> Write connect api_get -> Read connect api_stats -> OLAP connect api_delete -> Write