Messaging & social, an interactive architecture walkthrough
Social news feed (Twitter-style timeline): how the architecture works
How a social feed pushes posts into follower timelines, handles accounts with millions of followers by merging at read time, and ranks the result.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate.
Interactive diagram
Overview
A social news feed has two jobs: accept posts cheaply and show each reader a recent, ranked list of posts from the accounts they follow. The design choice is where to spend the work. Fan-out on write pushes each new post's ID into every follower's timeline list so a read is one lookup, while fan-out on read builds the timeline from the follow graph when it is opened. Public writing on Twitter's timelines describes pushing for most accounts and merging in the very large ones at read time, which is the hybrid sketched here.
Trade-offs and what changes at scale
Pushing makes reads fast and writes proportional to follower count, so one account with millions of followers can back up the queue and delay everyone else's timelines; skipping those accounts at write time and merging them on read bounds that cost, at the price of a slower, more complex read path and a follower-count threshold to tune. Timeline lists only cover active users and are capped, so memory is bounded and older history is rebuilt from the Post Store. Ranking adds latency and a feedback loop with engagement data, which this diagram leaves out. Fanout is at-least-once, so list inserts must tolerate duplicates, and a timeline can be briefly behind the Post Store (eventual consistency). Deletes, blocks and privacy changes must be applied at read time because pushed IDs are already in lists. This is a simplified teaching model, not Twitter's or X's actual current architecture.
How it works, step by step
The walkthrough above, as text. Each step lights up the components named under it.
A user publishes a post. The gateway authenticates the session and applies per-user write limits, which also limits spam volume before it costs any fanout work.
The Post Service validates the content, assigns a time-sortable ID (so IDs order by creation time without a separate timestamp lookup) and records any reply or repost reference.
The post is written to the Post Store first. It is the source of truth: every timeline holds only IDs that point back here, so rebuilding or losing a timeline list does not lose any post.
After the write succeeds, a new-post event is published to the Fanout Queue and the author gets a response. Delivery to followers happens afterwards, so the author does not wait for fanout, and a backlog delays timelines rather than failing the post.
Fanout Workers consume events, with events partitioned by author so one author's posts keep their order. Workers can be added when the queue lag grows.
For each event a worker asks the Social Graph Service for the author's followers, a page at a time. Accounts above the follower threshold (the celebrity case) are not expanded here: writing one post into tens of millions of lists would be the expensive part of the whole system.
For every active follower the worker pushes the post ID onto that follower's Home Timeline Cache list and trims it to a fixed length. Lists hold IDs rather than post bodies, which keeps memory small; users who have not been active recently have no list and are rebuilt on demand.
Following someone writes an edge in the Graph Store. Already-pushed timelines are not rewritten: the new account's posts appear from then on through fanout, and older posts only if the timeline is rebuilt or the account is merged at read time.
Opening the app calls the Timeline Service, which reads the user's list of post IDs from the Home Timeline Cache. This is a single list read, which is why this path is quick.
The service also asks the Social Graph Service which high-follower accounts this user follows, then pulls their latest posts straight from the Post Store and merges them with the pushed IDs by time. That is the read-time half of the hybrid: pushing for most accounts, pulling for a few very large ones.
The merged IDs are hydrated into full posts from the Post Cache, with misses read from the Post Store and filled into the cache. Hot posts are read by many timelines, so the cache absorbs most of that load.
The Ranking Service scores the candidates and applies visibility rules such as blocks and mutes, then the Timeline Service returns one page with a cursor. A purely chronological feed would skip scoring; a ranked one adds this hop and its latency budget.
If the cache has no list (a returning inactive user, or an evicted list), the service rebuilds it: it asks the Social Graph Service for the accounts the user follows, pulls their recent posts from the Post Store, and writes the list back to the cache. This is slower than a hit, so rebuilds are rate-limited.
Observability tracks the delay between a post and its arrival in follower lists, cache hit ratio and read latency. Fanout lag is the number to watch, since it directly sets how stale a timeline can be.
Sequence diagram
The same walkthrough as a UML sequence diagram, one lane per layer or group (13 components in all), left to right in the order a request reaches them, numbered by step. A loop on a lane is a step that stays inside that group. Solid arrows are synchronous calls, dashed are asynchronous.
Key components
Edgelayer
- API Gateway: TLS, auth, rate limiting
Write Pathdomain
- Fanout Queue: new-post events, partitioned by author (kafka)
- Fanout Workers: push post IDs to follower timelines
- Post Service: validate, assign ID, store
- Post Store: sharded by post ID; source of truth
Social Graphdomain
- Graph Store: follower and followee edges, sharded by user
- Social Graph Service: follows, followers, lists of followers
Read Pathdomain
- Home Timeline Cache: per-user list of recent post IDs (redis)
- Post Cache: hot post bodies and counters
- Ranking Service: scores candidates, applies visibility filters
- Timeline Service: merge, hydrate, rank, page
Observability
- Observability: metrics, fanout lag, alerts
Clientslayer
- Feed Client: web and mobile timeline, compose box
Sources
Public writing this explainer draws on. Read these for what the real systems actually do.
Make it yours
Copy this diagram and its walkthrough into your own workspace, then change anything: swap Postgres for DynamoDB, add a cache, rewrite the narration. Free, and it uses no AI credits.
Related walkthroughs
- Twitter-style timeline systemHow a timeline system fans tweets out to followers' cached timelines, pulls in large accounts at read time, and serves a home feed from cache.
- WhatsApp-style chat appHow a chat system holds millions of persistent connections, routes end-to-end encrypted messages, and falls back to push when users are offline.
- Notification system at scaleHow a notification platform validates requests, applies user preferences, queues by priority, and delivers push, SMS and email with retries and fallbacks.
This is a learning explainer based on public engineering writing and general design practice. It is simplified, it is not the actual architecture of any company, and it may be inaccurate. Real systems differ in the details. Browse the library.