Designing Twitter

01Requirements & scope

Pin the problem before drawing boxes. Interviews reward a crisp scope statement more than an exhaustive feature list.

Non-functional requirements

02Back-of-envelope estimation

Round numbers, stated assumptions. The goal is orders of magnitude that justify (or kill) design choices.

Traffic

Storage

03API design

REST over HTTPS at the edge; services speak gRPC internally. Cursor pagination everywhere — offsets don't survive a moving feed.

# Post a tweet (idempotency key dedupes client retries)
POST /v1/tweets
{ "text": "hello world", "media_ids": ["m_9f2c"], "reply_to": null,
  "idempotency_key": "c1a2-…" }
→ 201 { "tweet_id": "1849236481024917504", "created_at": … }

# Home timeline — cursor = last seen tweet ID (snowflake IDs are time-sortable)
GET /v1/timeline/home?cursor=1849236481024917504&count=20
→ 200 { "tweets": [ …hydrated tweets… ], "next_cursor": "…" }

GET  /v1/users/{id}/tweets?cursor=…&count=20   # user timeline
POST /v1/users/{id}/follow                     # idempotent
DELETE /v1/users/{id}/follow
POST /v1/tweets/{id}/like                      # counter, eventually consistent
POST /v1/tweets/{id}/retweet
GET  /v1/search?q=…&cursor=…                   # tweet search
GET  /v1/trends?place_id=…                     # trending topics

• Auth: OAuth 2.0 bearer tokens, validated at the API gateway; user ID flows to services in signed headers.
• Rate limits: per-user token buckets at the gateway (e.g. 300 tweets / 3 h, 900 timeline reads / 15 min) — protects fan-out from abuse.
• Media: client requests a presigned URL, uploads directly to object storage, then attaches the returned media_id — tweet write path never carries bytes.

04High-level architecture

Stateless services behind a gateway; synchronous work kept to the minimum, everything amplifying a write pushed through Kafka to async consumers.

Component responsibilities

05The write path: hybrid fan-out

The defining problem. Push (fan-out-on-write) gives cheap reads but explodes for celebrities; pull (fan-out-on-read) gives cheap writes but makes every read expensive. Twitter does both.

• Latency budget: median fan-out completes in < 5 s; a Lady Gaga-scale push would take minutes and melt Redis — hence the celebrity bypass.
• Active-only optimization: fan out only to followers active in the last ~30 days. An inactive user's timeline is rebuilt via pull when they return — this cuts fan-out volume by 50 %+.
• Ordering: partition Kafka by author ID so one author's tweets are processed in order; readers see global order via time-sortable Snowflake IDs, not delivery order.
• Unfollow / delete: lazy repair — filtered out at read time (hydration checks tweet existence and block/unfollow sets) rather than eagerly scrubbing millions of lists.

06The read path: serving a home timeline

1.2 M requests/s at peak, p99 under 200 ms. The invariant: the hot path touches only memory.

• Why store IDs, not full tweets, in timelines? 20 bytes vs ~1 KB per entry (50× less RAM), edits/deletes stay consistent (one canonical copy), and hydration hits a shared hot-tweet cache with a very high hit rate.
• Cold user (cache miss on the whole list): rebuild via pull — fetch following, grab each one's recent tweet IDs, merge, cache the result. One slow load (~1–2 s), fast thereafter.
• Graceful degradation: if the celebrity-merge or ranking step fails, serve the raw precomputed list — a slightly stale, unranked timeline beats an error.

07Data model & storage choices

Snowflake IDs — 64 bits, time-sortable, coordination-free

Every tweet needs a unique ID minted at 17 k/s across many hosts. Auto-increment can't be sharded; UUIDs aren't sortable. Snowflake packs time into the high bits so sorting by ID is sorting by time — which is what makes cursor pagination and timeline merging trivial.

Core tables

tweets    (tweet_id PK, author_id, text, media_ids[], reply_to, created_at)
          -- sharded by tweet_id → uniform write load; author timeline queries
          -- served by a per-author index/cache, not a cross-shard scan

users     (user_id PK, handle UNIQUE, display_name, bio, follower_count,
           following_count, created_at)          -- sharded by user_id

follows   (follower_id, followee_id, created_at)
          -- stored twice, sharded both ways:
          --   by followee_id → "who follows X"  (fan-out)
          --   by follower_id → "who does X follow" (pull merge)

likes     (user_id, tweet_id, created_at)       -- dedupe + counter source

Redis timeline structure

# One capped list per active user — IDs only, newest first
LPUSH timeline:{user_id} {tweet_id}
LTRIM timeline:{user_id} 0 799        # cap at 800 entries
EXPIRE timeline:{user_id} 2592000     # 30 d idle → evict, rebuild on return

Why these stores

08Deep dives

Search & trending

• Ingestion: index workers consume tweet_created from Kafka; tweets are searchable within seconds. The index is time-partitioned — a query starts at the newest partition and walks backwards, terminating early once it has enough results.
• Query: scatter-gather across shards of the relevant time partitions; blend recency + engagement for ranking.
• Trending: a streaming job (Flink/Storm) runs sliding-window counts over hashtags/phrases with a heavy-hitters sketch (count-min), scores by acceleration vs a historical baseline (so "Monday" never trends), segments by geo, and publishes top-K to a cache every ~60 s.

Engagement counters at scale

• A viral tweet takes thousands of likes/sec — a per-row DB counter becomes a hot spot. Instead: INCR sharded Redis counters (split hot keys into N sub-counters, sum on read), roll up to durable storage every few seconds.
• Display counts are eventually consistent and approximate ("1.2 M") — nobody audits them; the likes table remains the source of truth for "did I like this," which must be exact.

Availability & multi-region

• Stateless services scale horizontally behind LBs; Redis and DBs run replicated with automated failover.
• Multi-region: active-active for reads (each region holds full timeline caches), writes homed to one region per shard with async cross-region replication — a few seconds of cross-region staleness is within the consistency budget.
• Degradation ladder: drop ranking → serve stale cache → serve user-timeline-only. Never a blank feed.
• Back-pressure: if fan-out lag grows, Kafka absorbs the backlog — tweet posting never blocks; timelines just go slightly stale, and lag is the #1 dashboard metric.

Observability — what to watch

09Trade-offs & interview talking points

Extension questions to expect

• Ranked (ML) timeline? Keep the same candidate-generation machinery; insert a ranking service between hydration and response that scores ~500 candidates per request with engagement-prediction features.
• Real-time delivery (new-tweets banner)? WebSocket/SSE gateway subscribed to fan-out events for online users — push the signal, let the client pull the tweets through the normal read path.
• Edit/delete propagation? Nothing to fan out — timelines hold only IDs, so hydration reflects the canonical row immediately; just invalidate the tweet cache entry.
• Thundering herd on a viral tweet? Request coalescing at the cache layer (single flight), plus per-object hot-key replication in Memcached.