Twitter/X Timeline: Architecture Deep Dive

The timeline inbox is a per-user sorted list of post IDs — the pre-built result of all fanout-on-write operations targeting that user.

The inbox is typically stored in Redis as a sorted set: post IDs scored by timestamp. Insertion into a sorted structure is logarithmic in the number of entries. Reading a bounded recent range costs roughly the lookup plus the number of elements returned — not a literal O(1) operation, but the important architectural point is that it does not depend on how many accounts the user follows. That's the real improvement over generating a timeline from N followed accounts at read time: retrieval cost is bounded and independent of follow-graph size.

Inbox as Derived State

The Posts DB — durable post storage — is the source of truth for what was posted. The timeline inbox is derived, materialized state: a precomputed index built from fanout writes, not an independent record of anything. This distinction matters operationally. Losing an inbox does not mean losing a post — the underlying content is still safe in the Posts DB. What's lost is the precomputed pointer structure, which can be reconstructed from recent posts by followed authors, though rebuilding at scale has a real operational cost (see Failure & Scale Scenarios → Timeline Inbox Lost).

Deep-Scroll Behavior

A bounded, precomputed inbox is a good fit for the hot/recent window most users actually read — the first screen or two of a feed. It's a poor fit for a user who scrolls back far into their history: that older content may already have fallen off the bounded window and won't be present in the inbox at all. In this design, deep scrolling falls back to historical candidate retrieval — fetching older posts from followed authors directly rather than from the precomputed inbox — and that fallback result still needs to be merged, filtered, and ranked consistently with the rest of the feed rather than served as a raw, unranked list. Deep-scroll reads are rare relative to recent-feed reads, which is what makes the bounded-window trade-off worthwhile in the first place.

The fanout queue is the core coordination mechanism between post creation and follower inbox delivery.

When a normal user creates a post: (1) Post is written to Posts DB. (2) A single fanout job is enqueued containing: post ID, author ID, timestamp. (3) Fanout workers dequeue the job, look up the author's followers from the Social Graph, and write the post ID into each follower's inbox.

Fanout Job Chunking

A high-follower author doesn't literally create one queue message per follower — modeling a 50-million-follower author as 50 million instantaneous messages doesn't scale as a queueing strategy. A more scalable approach enqueues a single fanout task, then expands it in stages: obtain follower IDs in pages/chunks from the Social Graph, create bounded fanout batches from each page, and have workers process one batch at a time while checkpointing progress.

Backpressure

When fanout production outpaces worker throughput, queue depth rises and delivery lag grows. Autoscaling more workers helps up to the point where a downstream dependency — inbox storage, the Social Graph service — becomes the real limit. Priority and fairness policies prevent one author's fanout from monopolizing all workers and starving everyone else's posts. Under extreme, sustained overload, admission control or load shedding may be the only remaining option — deliberately delaying or dropping lower-priority fanout work to protect the system as a whole.

Idempotency and Retry

The idempotency key for a fanout write is the logical uniqueness of (timeline_owner_id, post_id) — a given post should appear at most once in a given follower's inbox no matter how many times the underlying job is retried. Using the post ID itself as the inbox set member (rather than, say, appending on every write) makes a retried write naturally idempotent: writing the same ID twice has the same effect as writing it once.

Fanout depends heavily on the Social Graph, but so far it's been treated as a black box. This layer looks at what the Social Graph actually needs to answer efficiently, and why.

How Is the Social Graph Used for Feed Fanout?

Both directions matter enough that they typically need efficient representation of their own, rather than deriving one direction from the other at request time — computing "who follows this author" by scanning every user's following list would be far too slow to run per fanout job.

How Is the Social Graph Stored and Accessed?

The access patterns here are largely adjacency-list style lookups — for a given ID, retrieve the (possibly very large) set of connected IDs. This can be implemented with a graph database, but a graph database isn't automatically the correct choice — the same adjacency-list access pattern can be implemented with a relational store partitioned by user/account ID, a key-value store keyed by user ID, or a dedicated graph engine, depending on operational familiarity and existing infrastructure. What matters architecturally is the access pattern, not the vendor.

What Happens on Follow / Unfollow?

A follow or unfollow changes a graph edge, which changes future fanout behavior going forward — an unfollowed author's future posts stop being pushed to that reader. It does not require synchronously rewriting that reader's existing cached timeline or inbox; read-time visibility filtering (see Post Lifecycle & Visibility) can exclude posts from an unfollowed author going forward without needing an immediate, synchronous cleanup pass across historical inbox entries.

The threshold that separates fanout-on-write users from fanout-on-read (celebrity) users is a tunable parameter, not a hard architectural boundary.

Follower count is a useful proxy for fanout cost, but it isn't the only thing that determines it. Fanout cost is closer to posts × followers actually receiving the push — which means posting frequency, the percentage of followers who are actually active, fanout queue capacity, and worker throughput all matter too. For illustration, a system might initially classify accounts above a high follower-count threshold as pull candidates, then tune that threshold from observed fanout cost and queue saturation — rather than treating any single number as a permanent architectural constant.

Strategy Transitions

The important transition here is in the author's distribution strategy, not a claim that "the follower's inbox becomes incomplete" — the inbox was never meant to be a complete record in the first place. When an author moves from push to pull: future posts simply stop being pushed; followers' existing inboxes may still contain older posts from that author, which is fine since those posts already happened; and read-time composition begins including new posts from that author going forward. Deduplication at merge time prevents the same post from appearing twice during the transition window.

When an author moves the other way — pull to push — future posts can begin fanout immediately. Backfilling that author's older posts into every follower's inbox is optional, and whether to do it at all is a product decision (does the value of retroactively surfacing older posts justify the fanout cost?) rather than a technical requirement.

How Does Twitter Generate Timeline Candidates? Ranking never runs over every post in the system — it runs over a bounded candidate pool assembled just before ranking happens.

Candidate Sources

For this design: the precomputed timeline inbox (from fanout-on-write), pull-time reads from celebrity/pull-strategy authors the user follows, and — optionally, if the product scope includes a For You-style feed — additional recommendation sources. The Following feed and a recommendation feed are conceptually separate candidate sources; mixing them silently would turn this design into a full recommendation system, which is out of scope here.

Merge

Each candidate source returns a bounded set. Composition merges them, deduplicates by post ID (a post can otherwise arrive from more than one source), discards candidates already known to be invalid or expired, and passes the resulting pool forward to ranking.

Candidate Filtering

Before anything is served, the candidate pool is filtered on deletion state, visibility rules, block/mute relationships, account state (suspended/private), and duplicate or repost policy. This connects directly to Post Lifecycle & Visibility — filtering here is what actually prevents removed or unauthorized content from reaching the reader, even though it may still physically exist as an ID somewhere in a candidate list.

How Do You Paginate a Ranked Feed? Infinite scrolling is a core feed behavior, and a continuously changing, continuously re-ranked feed makes ordinary pagination surprisingly hard.

Why Offset Pagination Doesn't Fit

Offset-based pagination ("give me results 20-40") assumes a stable, unchanging ordered dataset. A feed doesn't hold still: new posts arrive and can shift where things sit, ranked scores can change between requests, and an offset computed against a slightly different underlying order can duplicate results the reader already saw or skip results entirely. Deep offsets are also inefficient against many storage access patterns.

Cursor Model

A cursor is a conceptually opaque token carrying enough state to continue from exactly where the previous page left off. For a simple chronological candidate list, that state might just be an ordering key (timestamp) plus a post-ID tie-breaker for entries sharing the same timestamp. For a ranked feed, this is harder, because the score that determined position last time might not be the same score if computed fresh again.

Practical Approaches

None of these is a universal answer — the right choice depends on how much staleness the product can tolerate versus how much implementation complexity is acceptable. See Trade-offs & Decisions → Offset vs Cursor Pagination for how to weigh that choice, and SeeItFlow's general cursor-pagination content for the pattern outside the feed-specific context here.

The ranking service takes a pool of candidate post IDs and produces an ordered list for the user's timeline.

Ranking is not one monolithic step — it's a pipeline: candidate generation produces a bounded pool (see Candidate Generation & Feed Composition), filtering removes invalid or unauthorized candidates, feature hydration fetches the signals each remaining candidate needs to be scored, scoring assigns each candidate an order, post-ranking rules adjust that order for product concerns, and the final top K is served to the client.

Feature Categories

Scoring Approaches

A real system doesn't need to start with a machine-learning model. A reasonable progression is: reverse-chronological ordering as a baseline, then a heuristic weighted score combining a handful of the features above, then — once there's enough engagement data and the product justifies the investment — a learned ranking model. Many production feed systems run a two-stage ranker: a cheap first-pass score narrows a large candidate set down to a smaller shortlist, and a more expensive model scores only that shortlist. This keeps the expensive model's cost bounded regardless of how large the initial candidate pool is.

Post-Ranking Rules

The raw model score usually isn't the final order. Post-ranking rules can enforce diversity (avoid an entire feed page from one author or topic), deduplicate near-identical or already-seen content, cap how many consecutive posts come from the same author, apply freshness constraints so that very recent posts aren't buried purely on a lower predicted score, and apply product or business rules that sit outside the model entirely.

What happens when the ranking model itself is slow or unavailable is a failure-handling question, not a ranking-mechanics one — see Failure & Scale Scenarios → Ranking Service Unavailable for the fallback behavior and timeout budget.

How Are Deleted Posts Removed from Timelines? A post can already be fanned out into millions of candidate inboxes by the time it becomes unavailable — deleted, blocked, or otherwise no longer visible to a given reader.

Synchronously deleting a post's ID from every inbox it was fanned out to is expensive at scale and, importantly, unnecessary for immediate correctness — because inboxes only ever stored IDs, not content.

Serving-Time Validation

The read path already fetches candidate IDs, then hydrates and filters posts before serving — so discarding a deleted or now-inaccessible post at that step is a natural extension of work already happening, not new machinery. The sequence: fetch candidate IDs → hydrate/filter posts → discard deleted or inaccessible content → optionally perform asynchronous cleanup of the now-stale inbox reference sometime later.

This same serving-time filtering handles post deletion, account suspension, a private/visibility change, a block, a mute (where applicable), an unfollow, and a deleted repost — all of them are cases where a candidate ID exists somewhere in derived state but should not be served.

Cache Invalidation

The same event needs to be reflected across the post/object cache (so a deleted post's cached copy doesn't keep being served), the final composed timeline cache (so a cached page doesn't keep including it), and any visibility-metadata cache. Faster cache invalidation reduces the window where stale content is still visible, but read-time filtering is what guarantees correctness even if invalidation is delayed.

This is also the clearest illustration of why storing IDs — not full post objects — in every timeline is valuable: a single deletion event only has to update one canonical record (the post itself), not every derived copy scattered across millions of inboxes.

How Is a Social Media Timeline Stored? Stepping back from any single layer, it's worth mapping every kind of data in this design to its logical storage role — the distinction between source of truth, derived state, and cache matters more than which specific database is chosen.

Three categories matter more than any specific vendor choice. Source of truth — data that, if lost, is genuinely lost (Posts, Follow edges). Derived state — data computed from the source of truth that can be rebuilt, at some operational cost, if lost (the timeline inbox, engagement aggregates). Cache — data that's cheap and expected to be rebuilt constantly, with no rebuild cost worth discussing (object cache, result cache). Every failure-mode question in this design — what's actually lost, what needs a rebuild, what just gets slower — traces back to which of these three categories the affected data falls into.

"Timeline caching" undersells what's actually happening — a production feed has several distinct cache layers, each with different content, different invalidation rules, and different freshness requirements.

Object/Post Cache

Caches hydrated post and author metadata — text, media, author info, engagement counts — with a TTL of minutes to hours. Counter values (likes, replies) are updated via increment operations rather than full invalidation, which keeps hit rates high while counts stay reasonably fresh.

Timeline Inbox / Candidate Storage

This isn't a cache in the usual disposable sense — it's derived, materialized feed state (see Timeline Inbox Internals). Losing it costs a rebuild, not just a slower read, which is why it deserves separate treatment from the caches below.

Ranked Timeline / Result Cache

Caches a composed, ranked page of feed results per user, with a short TTL — for illustration, on the order of tens of seconds. On a new post from a followed account, the system can optionally prepend the post into the cached result rather than invalidating it outright, reducing miss rate. On follow/unfollow, the cached result for that user is invalidated since the candidate pool itself changed.

Graph/Metadata Caches

Follower counts, push/pull classification, and other relationship metadata are read far more often than they change, making them good cache candidates with asynchronous refresh rather than synchronous lookups on every fanout decision.

Each of these layers has different invalidation and freshness behavior — treating them as one undifferentiated "cache" hides real design decisions about what can be stale, for how long, and what must be invalidated immediately versus what can just expire.

Cache Stampede