System Design Handbook · llms.txt
Twitter is a service where people post short public messages called tweets. When you follow someone, their tweets show up in your home timeline, the feed of tweets from everyone you follow. The tweets one person has posted make up their user timeline. Anyone can also search all recent tweets by keyword, for example "world cup final".
Those features pull the design in different directions. One tweet from a user with 30 million followers has to appear in 30 million home timelines within seconds. Millions of people open their home timeline many times a day and expect it to load instantly. Search has to find a tweet posted ten seconds ago among billions of others. The interesting question is where to do the work: when a tweet is written, when a timeline is read, or somewhere in between.
"Design the Facebook feed" and "Design Facebook search" are close cousins of this question, so the same answer works for them with small changes.
This chapter follows the four steps from The system design interview, step by step. The social news feed chapter goes deeper into fan-out strategies, cursor pagination and ranking. This one covers enough fan-out to stand alone, then spends its depth on the parts specific to Twitter: the services that build and read timelines, keyword search, notifications, and how each piece scales.
We'll scope the problem to these use cases:
These numbers are hypothetical inputs for the exercise. They describe no real service.
General:
Timeline:
Search:
Ask the interviewer whether they want these numbers before working them out. A month has 30 × 86,400 s = 2,592,000 seconds, about 2.6 million. All rates below are averages. Because traffic is uneven, we'll also assume peaks of about 3× the average.
Size of one tweet.
tweet_id: 8 bytes (a 64-bit integer).user_id: 8 bytes (also a 64-bit integer).text: 140 bytes, if the text is ASCII. A 140-character tweet in other scripts or with emoji takes more bytes, because UTF-8 uses up to 4 bytes per character.media (photos and video): 10 KB on average across all tweets, since most tweets have none.Storage.
Request rates.
Bandwidth.
Memory for home timelines.
What these numbers tell us.
The estimation chapter explains the method behind this arithmetic.
Each component, and why it's there:
Posting has two jobs: save the tweet in the author's user timeline, and deliver it to every follower's home timeline.
Saving the tweet. The user timeline fits a relational database well. Each tweet is one row, and "user 123's tweets, newest first" is one index lookup.
CREATE TABLE users (
user_id BIGINT PRIMARY KEY,
handle VARCHAR(15) NOT NULL UNIQUE,
name VARCHAR(50) NOT NULL,
created_at TIMESTAMP NOT NULL
);
CREATE TABLE tweets (
tweet_id BIGINT PRIMARY KEY, -- time-ordered, so newer ids are larger
user_id BIGINT NOT NULL,
text VARCHAR(140) NOT NULL,
media_ids VARCHAR(255), -- keys in the object store, if any
reply_to_tweet_id BIGINT NULL,
created_at TIMESTAMP NOT NULL,
INDEX idx_user_timeline (user_id, tweet_id DESC)
);
CREATE TABLE follows (
follower_id BIGINT NOT NULL,
followee_id BIGINT NOT NULL,
created_at TIMESTAMP NOT NULL,
PRIMARY KEY (follower_id, followee_id), -- whom does X follow?
INDEX idx_followers (followee_id, follower_id) -- who follows X?
);
Tweet ids are time-ordered: a later id is always larger, so sorting by tweet_id sorts by time, and any server can create ids without a central counter. See Snowflake-style IDs. A NoSQL store would also work, since every access is by tweet_id or user_id (see SQL or NoSQL). We start with SQL and revisit it in step 4.
Delivering the tweet. Delivery is the hard part. At 58,000 deliveries a second on average and 175,000 at peak, writing each one as a row in a relational database would overload it, because every insert updates indexes and writes a log to disk. We want a store with very fast writes: a NoSQL database or an in-memory cache. Memory also wins on reads. In the latency table credited to Jeff Dean and Peter Norvig (circa 2012), reading 1 MB sequentially takes about 250 µs from memory, 4 times longer from an SSD, and 80 times longer from a spinning disk.
Photos and videos go to an object store, a storage service for large files addressed by key. The client uploads them first and gets back media ids, which the tweet refers to.
The write path, step by step:
tweet_id, and saves the tweet's media in the object store if it came with the request.tweets table. This is the author's user timeline.201 Created to the client. The author doesn't wait for delivery.Fan-out on write, and its weak spot. This approach is called fan-out on write, or push. Each home timeline is built when tweets are posted, so a read just fetches a finished list. The opposite is fan-out on read, or pull: nothing is precomputed, and opening the app looks up everyone you follow, fetches their recent tweets and merges them. Pull makes posting cheap and reading expensive. Push does the reverse.
Push has a weak spot: users with huge followings. One tweet from an account with 30 million followers needs 30 million timeline inserts. If the fan-out fleet is sized for our peak of 175,000 deliveries a second, that's 30,000,000 ÷ 175,000 ≈ 171 seconds, almost 3 minutes of the entire fleet's capacity. Everyone else's tweets wait behind it. This is the celebrity problem. Step 4 fixes it with a hybrid: push for most authors and pull for the few with the most followers. The social news feed chapter compares push, pull and the hybrid in depth.
What a home timeline looks like in memory. If the memory cache is Redis, each home timeline can be a Redis list: an ordered sequence of values under one key, such as home:456. Each element is 17 bytes:
newest tweet next tweet older tweet
| 8 bytes 8 bytes 1 byte | 8 bytes 8 bytes 1 byte | 8 bytes 8 bytes 1 byte |
| tweet_id user_id flags | tweet_id user_id flags | tweet_id user_id flags |
The flags byte marks things like "this is a retweet" or "this is a reply", for filtering at read time. The list stores only ids. Text and author names are looked up when the timeline is read, which keeps entries small and means a profile edit doesn't rewrite millions of timelines.
Ask the interviewer how much code they expect. Here is the fan-out service as a short Python sketch:
import struct
ENTRY = struct.Struct(">QQB") # tweet_id, user_id, flags: 17 bytes
TIMELINE_LENGTH = 800 # entries kept per home timeline
BATCH_SIZE = 1_000 # followers handled per round trip
def fan_out(tweet, user_graph, timelines, search_index, notifications):
"""Deliver one new tweet. Runs after the tweet is saved in SQL."""
search_index.add(tweet) # one write, to one search shard
entry = ENTRY.pack(tweet.tweet_id, tweet.user_id, tweet.flags)
for batch in user_graph.followers(tweet.user_id, batch_size=BATCH_SIZE):
pipe = timelines.pipeline() # send many commands in one round trip
for follower_id in batch:
key = f"home:{follower_id}"
pipe.lpush(key, entry) # newest at the head
pipe.ltrim(key, 0, TIMELINE_LENGTH - 1) # drop the oldest
pipe.execute()
subscribers = user_graph.notification_subscribers(tweet.user_id)
if subscribers:
notifications.enqueue({"tweet_id": tweet.tweet_id,
"recipients": subscribers})
A few details matter:
LPUSH then LTRIM key 0 799 caps the list at 800 entries. The Redis documentation notes that LTRIM is O(1) in this pattern, because usually one element falls off the end.The API. The public API is REST over HTTPS. REST means each URL names a resource and standard HTTP methods act on it. See REST.
POST /api/v1/tweets HTTP/1.1
Host: api.twitter.example
Authorization: Bearer ABC123
Content-Type: application/json
{
"status": "hello world!",
"media_ids": ["ABC987"]
}
HTTP/1.1 201 Created
Content-Type: application/json
{
"tweet_id": "1849203948572610560",
"user_id": "123",
"status": "hello world!",
"media_ids": ["ABC987"],
"created_at": "2026-10-19T14:03:11Z"
}
The server learns the author from the access token, so the client doesn't send user_id. Ids are strings in JSON because a 64-bit integer can lose precision when JavaScript reads it as a number.
Inside the data center, services call each other with RPC (remote procedure calls), such as TweetInfo.MultiGet(ids). RPC frameworks send compact binary messages, which suits many small internal calls. See RPC and REST side by side.
Thanks to fan-out on write, the home timeline is already built. Reading it means fetching a list of ids and filling in the details, called hydration.
LRANGE as O(S + N), where S is the start offset and N the number of entries returned, so reading from the head costs only the entries read;MGET). This is O(n) in the number of tweets on the page;def home_timeline(user_id, count=20, max_id=None):
raw = timelines.lrange(f"home:{user_id}", 0, TIMELINE_LENGTH - 1)
if not raw and not timelines.exists(f"home:{user_id}"):
raw = rebuild_timeline(user_id) # inactive user: see step 4
entries = [ENTRY.unpack(r) for r in raw] # (tweet_id, user_id, flags)
if max_id is not None: # the next page starts below
entries = [e for e in entries if e[0] < max_id]
page = entries[:count]
tweets = tweet_info.multiget([tweet_id for tweet_id, _, _ in page])
users = user_info.multiget({author_id for _, author_id, _ in page})
return [
{**tweets[tweet_id], "user": users[author_id]}
for tweet_id, author_id, _ in page
if tweet_id in tweets # skip tweets deleted since delivery
]
The client pages backward with max_id, meaning "tweets older than the last one I saw." Because tweet ids grow with time, this works as a cursor, and new tweets arriving at the top don't shift later pages. See cursor-based pagination. Reading the whole 800-entry list is only 13.6 KB, so the sketch keeps it simple.
The API:
GET /api/v1/home_timeline?count=20 HTTP/1.1
Authorization: Bearer ABC123
HTTP/1.1 200 OK
Content-Type: application/json
{
"tweets": [
{"tweet_id": "1849203948572610560", "user_id": "456",
"user": {"handle": "ada", "name": "Ada"}, "status": "foo"},
{"tweet_id": "1849203911134265345", "user_id": "789",
"user": {"handle": "grace", "name": "Grace"}, "status": "bar"},
{"tweet_id": "1849203870012846080", "user_id": "789",
"user": {"handle": "grace", "name": "Grace"}, "status": "baz"}
],
"next_max_id": "1849203870012846079"
}
The user timeline is one person's own tweets. It's much simpler, because there's no merging across authors.
(user_id, tweet_id DESC) index:SELECT tweet_id, user_id, text, media_ids, created_at
FROM tweets
WHERE user_id = :user_id AND tweet_id < :max_id
ORDER BY tweet_id DESC
LIMIT 20;
The REST API matches the home timeline's, except every tweet comes from the one user:
GET /api/v1/user_timeline?user_id=123&count=20 HTTP/1.1
Because popular profiles are viewed far more often than they change, the read API can cache the first page of each user timeline in the memory cache. Step 4 uses that cache to serve celebrities' tweets.
Search works in the opposite direction from the home timeline. A tweet is indexed once, on one server, and each query asks every server.
Indexing a tweet. When the fan-out service adds a tweet to the search index, the indexer splits its text into terms (words, hashtags, mentions), normalizes them, and adds the tweet id to an inverted index. An inverted index maps each term to the tweet ids that contain it, like the index at the back of a book, with each list kept newest first. Tweets are spread over the search servers by a hash of the tweet id, so each tweet goes to exactly one shard, or slice of the index. The search engine chapter covers inverted indexes in depth.
Answering a query:
hello AND world.The search service in Python, as a sketch:
import re
import time
from concurrent.futures import ThreadPoolExecutor, wait
MARKUP = re.compile(r"<[^>]+>")
TERM = re.compile(r"[#@]?\w+") # keep hashtags and mentions whole
def parse_query(raw, spelling):
text = MARKUP.sub(" ", raw) # remove markup
terms = TERM.findall(text) # break into terms
terms = [spelling.correct(t) for t in terms] # fix typos
terms = [t.lower() for t in terms] # normalize case
return {"op": "AND", "terms": terms} # boolean query
def search(raw, shards, spelling, pool: ThreadPoolExecutor,
limit=20, timeout_s=0.1):
query = parse_query(raw, spelling)
futures = [pool.submit(shard.search, query, limit) for shard in shards]
done, _ = wait(futures, timeout=timeout_s) # scatter, with a deadline
hits = []
for f in done: # gather
if f.exception() is None:
hits.extend(f.result()) # each hit: tweet_id, matched terms, counts
now_ms = time.time() * 1000
hits.sort(key=lambda h: rank(h, now_ms), reverse=True) # merge, rank, sort
return hits[:limit]
def rank(hit, now_ms):
age_hours = (now_ms - hit.created_ms) / 3_600_000
engagement = 1 + hit.retweets + hit.likes + hit.replies
return engagement ** 0.5 / (1 + age_hours) # fresh and popular first
Each shard returns only its own best limit hits, so the service receives at most limit × number of shards results. The deadline matters: waiting for one slow shard would make every query slow, so the service returns what it has and accepts slightly incomplete results. The ranking function is a toy that favors recent, popular tweets. A real one would also weigh whom the searcher follows.
The indexer must normalize tweets exactly as the parser normalizes queries. If tweets keep their capital letters and queries don't, "World" in a tweet never matches "world" in a query. Typo fixing is the exception: it runs only on queries, often as a "did you mean" suggestion.
The REST API:
GET /api/v1/search?query=hello+world HTTP/1.1
The response looks like the home timeline's, except the tweets are the ones that match the query.
How Twitter did it, around 2011. A 2012 paper by Twitter engineers, Earlybird: Real-Time Search at Twitter, describes the search system as of fall 2011. Tweets passed through an ingestion pipeline, where they were tokenized and annotated with metadata such as language. They were then hash-partitioned across Earlybird servers, which were built on Lucene and held their indexes in memory. At query time a front end called Blender parsed the query and sent it to multiple Earlybird servers. Blender then merged and re-ranked their results. The paper reports more than two billion queries a day at an average latency of 50 ms, with tweets usually searchable within 10 seconds of being posted.
Don't jump straight from the first design to this one. In an interview, and in real life, scaling is a loop:
The scaling on AWS chapter shows this loop step by step for one system. Here we'll use the step-1 numbers to find the bottlenecks, then add the components above one at a time. Internal load balancers between the tiers are left out of the diagram to reduce clutter.
The numbers point to five pressure points:
The fan-out service is a likely bottleneck. As step 3 showed, one tweet from a user with millions of followers can take minutes to deliver.
Slow fan-out also causes race conditions, where the result depends on which of two operations finishes first. A celebrity tweets, and someone with few followers replies within seconds. The reply is delivered almost at once, while the original is still working through millions of timelines, so a user who follows both sees the reply first. One fix is to reorder tweets at serve time: sort each page by the time-ordered tweet_id, and if a reply's original is missing, fetch it from the tweet info service and show it first.
A better fix is to stop fanning out tweets from highly followed users. Pick a threshold, for example 100,000 followers; the exact number is a tuning choice. For authors above it:
tweet_id.CELEBRITY_THRESHOLD = 100_000
def fan_out_targets(author_id, user_graph):
if user_graph.follower_count(author_id) >= CELEBRITY_THRESHOLD:
return [] # pulled in at read time instead
return user_graph.followers(author_id, batch_size=BATCH_SIZE)
def merge_celebrities(user_id, entries, recent_tweets):
"""entries: this user's precomputed (tweet_id, user_id, flags) list."""
for celeb_id in user_graph.followed_celebrities(user_id):
for tweet_id in recent_tweets(celeb_id, limit=50):
entries.append((tweet_id, celeb_id, 0))
entries.sort(key=lambda e: e[0], reverse=True) # re-order at serve time
return entries[:TIMELINE_LENGTH]
The trade-off: a timeline read now does a little more work, one extra lookup per celebrity the user follows. In return, posting stays cheap for everyone, and a celebrity's followers all see the tweet at about the same time. A celebrity's recent tweets are read by millions of users, so they make very effective cache entries.
How Twitter did it, around 2012. At QCon San Francisco in 2012, Twitter's Raffi Krikorian gave a talk called "Timelines at Scale", published by InfoQ in 2013. High Scalability's summary of the talk reports these details:
The summary also gives about 30 billion timeline deliveries a day against about 400 million tweets, an average of 30 billion ÷ 400 million = 75 deliveries per tweet. Our assumption of 10 is low by comparison, so a real fan-out fleet would need to be several times larger than our estimate.
RAM is fast and expensive. These limits keep the memory cache a manageable size:
Keep only several hundred tweets per home timeline. We picked 800, which is the 13.6 KB per user from step 1. A user who scrolls further back falls through to a slower path that reads from the database.
Keep only active users' home timelines. If a user hasn't been active in the past 30 days, don't fan out to them, and let their timeline expire from the cache. When they return, rebuild their timeline:
tweet_id, and keep the newest 800.The first load after a long absence is slower. In exchange, the cache skips memory and fan-out writes for users who would never have read them.
Store only a month of tweets in the tweet info service. Timelines show recent tweets, so a month covers almost every read. That's 15 billion tweets × 200 bytes ≈ 3 TB of memory. Older tweets are read from the database on a cache miss.
Store only active users in the user info service. At an assumed 1 KB per profile, 100 million active users take 100 GB.
Replicate the cache. Keep each timeline on more than one cache server, as Twitter did with 3 copies. Losing a cache server then doesn't force a rebuild of millions of timelines from the database at once.
def rebuild_timeline(user_id):
followees = user_graph.following(user_id)
rows = sql.query(
"SELECT tweet_id, user_id FROM tweets "
"WHERE user_id IN %s AND created_at > NOW() - INTERVAL 30 DAY "
"ORDER BY tweet_id DESC LIMIT %s",
(tuple(followees), TIMELINE_LENGTH),
)
entries = [ENTRY.pack(r.tweet_id, r.user_id, 0) for r in rows]
key = f"home:{user_id}"
pipe = timelines.pipeline()
pipe.delete(key)
if entries:
pipe.rpush(key, *entries) # already newest first
pipe.expire(key, 30 * 86_400) # refreshed on each read
pipe.execute()
return entries
With sharded tweet storage this becomes one query per shard plus a merge, which is slow, so it should be rare.
The search cluster would likely need to keep its index in memory to keep latency low. Suppose search covers the last 7 days, which is 3.5 billion tweets. In 2011, a fully loaded Earlybird server held 144 million tweets and handled about 5,000 queries a second, according to the Earlybird paper. On hardware like that:
More replicas add query capacity. More shards hold more tweets, but every query then waits on more servers, so the slowest one matters more. Older tweets can live in a slower tier that's searched only when recent results run short. The search engine chapter compares partitioning schemes.
The memory cache takes most reads off the database, but SQL read replicas (copies that receive every change from the primary and serve reads) alone are unlikely to handle the cache misses: user timelines, deep scrolling, rebuilds and tweets older than a month. Writes are worse. 17,000 inserts a second at peak, each updating several indexes, plus 3 TB of new rows a month, would overwhelm a single SQL write primary with a standby. We need more scaling patterns:
tweets table across many databases. Sharding by user_id keeps each user timeline on one shard, so the most common query touches one server. The cost is that celebrities make their shard hot, and a timeline rebuild has to ask many shards. See sharding.We should also consider moving some data to a NoSQL database. Tweets are written once, read by id or by author, and almost never joined, which is a good match for a wide-column or key-value store designed for heavy write loads. The follower graph could move to a store built for adjacency lists. See NoSQL databases and the social graph design.
The notification service puts each "tell these followers about this tweet" job on a queue. Workers take jobs off it and call the push and email providers, which keeps slow outside services off the fan-out path. In a burst the queue grows and workers catch up later, so notifications can arrive late. A worker that crashes after sending but before acknowledging a job can send it twice, so workers should record what they've sent and skip duplicates. See queues and async work and the notification system design.
The last use case was high availability. Every tier above runs on more than one machine:
The design also chooses eventual consistency: a follower might see a tweet a few seconds after it's posted, and two followers might see it at slightly different times. That's acceptable for a timeline and lets the system keep serving reads when parts of it fail. See availability and CAP and consistency.
These are the decisions an interviewer is most likely to probe.
Push, pull or hybrid for home timelines. Pull makes posting cheap and every read expensive: one lookup per account followed, on every load. Push makes reads cheap and posting expensive, and it has the celebrity problem. With 17 reads per tweet and a delivery target of a few seconds, push for ordinary users plus pull for the most-followed accounts is the best fit. The interesting follow-up is the threshold: raising it means more fan-out work, and lowering it means more merging at read time. See the social news feed chapter.
Memory cache or durable store for timelines. Timelines kept only in memory are fast to read and write, but losing a cache server means rebuilding its timelines from the database. A durable NoSQL store survives restarts but costs more per operation. We keep timelines in memory, replicate them, and treat SQL as the source of truth that can rebuild any timeline. See when to update the cache.
Ids or whole tweets in each timeline. Ids keep entries at 17 bytes and make edits and deletes take effect everywhere at once, at the cost of a hydration step on every read. Whole tweets would skip hydration but multiply memory many times over, and a profile change would mean millions of rewrites. Ids win.
SQL or NoSQL for tweets. SQL brings transactions, flexible queries and familiar tools, and it's enough at first. At 15 billion new rows a month, SQL sharded by user_id and a wide-column NoSQL store end up looking much alike. Choose by what your team can operate. See SQL or NoSQL.
How to split the search index. Splitting by tweet means indexing touches one shard and every query asks all of them. Splitting by term would let a query touch only its terms' shards, but every new tweet would write to many shards, and a trending hashtag would overload one. With a high write rate and short queries, split by tweet, and split again by time, because most searches want recent tweets. See the search engine chapter.
Ordering and consistency. Fan-out delivers tweets out of order, and replicas lag. We accept eventual consistency, reorder by tweet_id at serve time, and give authors read-your-own-writes on their own tweets. See guarantees for one user.
Queues and back pressure. Fan-out and notifications run from queues, so posting stays fast and bursts are absorbed. If a queue keeps growing, the system needs back pressure, such as delaying fan-out to the least active users first.
REST outside, RPC inside. REST is easy for outside developers and caches well. RPC is compact and fast between internal services, which also need service discovery. The public API needs authentication, rate limiting and the other security basics. Keep benchmarking and monitoring as the system grows, since scaling is never finished.
Each entry is 17 bytes, so one timeline is 500 × 17 B = 8,500 B, about 8.5 KB. For 200 million users that's 200 million × 8.5 KB = 1.7 TB, and 3.4 TB with 2 copies. The cache's own structures add overhead per element, so measure it on a sample before buying hardware. Even if it doubles the total, about 7 TB is practical on a cluster of large-memory servers.
50,000,000 ÷ 200,000 = 250 seconds, about 4 minutes of the whole fleet's capacity. Ordinary users' tweets queue behind it, the celebrity's followers see the tweet minutes apart, and replies can arrive before the tweet itself.
Use the hybrid. Skip fan-out for accounts above a follower threshold, keep their recent tweets in a small, heavily cached list (or find them through search), and merge them into each reader's timeline at read time, sorted by tweet id.
The original came from an account with many followers, so its fan-out took minutes. The reply came from an account with few followers and was delivered almost at once. Fix it at serve time: sort each page by the time-ordered tweet_id, and if a reply's original isn't on the page, fetch it from the tweet info service and show it first. The hybrid removes most of these races too, because big accounts' tweets are merged in at read time.
Their timeline expired from the memory cache after 30 days, and fan-out stopped writing to it. The timeline service finds no list, asks the user graph service whom they follow, reads those accounts' recent tweets from the SQL shards, merges them by tweet_id, keeps the newest 800 and writes the list to the cache. It then hydrates the first page and marks the user active, so fan-out resumes. That first load is slower. The design accepts this for a rare event, in exchange for not storing or fanning out to tens of millions of inactive users.
The service strips the markup, leaving "World Cup FINAL". It splits that into three terms, checks each for typos, and lowercases them to world, cup and final. It builds world AND cup AND final and sends it to every shard at once. Each shard intersects its lists for the three terms and returns its best 20 matches. The service waits up to its deadline, merges the lists, ranks them by recency and engagement, and hydrates the top 20 like a timeline. If the indexer hadn't lowercased tweets the same way, final would never match a tweet that said "Final".
At read time, in the timeline service. Each timeline entry already has a flags byte that marks retweets. When hydrating a page, the service loads the reader's set of accounts whose retweets they've hidden and drops matching entries, reading a few extra entries so the page still holds 20 tweets. Filtering at write time would make fan-out check every follower's settings for every tweet, and a changed setting would need the timeline rewritten. Filtering at read time costs a little per read and takes effect immediately.
Previous: Design a URL shortener (like TinyURL or Bitly) · Next: Design a social media news feed (like Facebook, Instagram, or Twitter)