Design a Timeline and Tweet Service (Twitter)

Tweet Service & Cassandra CommitLog CDC Pattern

The Tweet Service handles tweet validation and durable persistence, ensuring write API responses complete in under 100 ms while eliminating application-level dual-write failure windows.

When a user posts a tweet, writing directly to both the database and Kafka creates a dual-write failure risk where the database write succeeds but Kafka publication fails, resulting in ghost tweets that never fan out. To maintain consistency without requiring cross-partition distributed transactions, the Tweet Service commits the tweet record directly to the authoritative Cassandra tweets table.

Cassandra writes mutations sequentially to its on-disk CommitLog before acknowledging the write. A dedicated Cassandra Change Data Capture (CDC) connector acts as a durable, replayable bridge tailing the commit log on disk and publishing events to the tweet-events Kafka topic with connector-level at-least-once delivery, subject to connector uptime, offset tracking, and commit-log retention. The Tweet API responds with HTTP 201 Created as soon as Cassandra commits, leaving fan-out, search indexing, and push notifications to asynchronous downstream workers.

Interaction Service & Real-Time Counter Pipeline

User interactions including likes and retweets require low-latency serving counters alongside durable event logging.

When a user interacts with a tweet (POST /api/v1/tweets/{tweet_id}/like), the Interaction Service records the state durably in relational storage, publishes a like-events message to Kafka, and atomically updates real-time counters in Redis (HINCRBY tweet:counters:{tweet_id} like_count 1). During Step 6 (Hydration) of the timeline read pipeline, these counters are merged into the tweet object payload, while the ML Ranking Service consumes real-time interaction velocities to score and surface trending candidate tweets.

Timeline Service & 7-Stage Read Pipeline

The Timeline Service orchestrates timeline assembly across precomputed Redis caches and live candidate streams.

While Redis retains up to 800 tweet IDs per active user (subject to a sliding 48-hour TTL) to support continuous scrolling, each home timeline request evaluates a bounded working set through a structured 7-stage pipeline:

1. Candidate Generation: Fetches a bounded window of ~200 precomputed tweet IDs from the user's Redis timeline sorted set (timeline:home:{user_id}) for normal followees, and queries the latest ~100 recent tweet IDs from followed celebrity caches (timeline:user:{celeb_id}) in parallel, assembling roughly 300 candidate tweet IDs.
2. Visibility Filtering: Checks cached follow graph sets, mute lists, and block lists in Redis to filter out content from users no longer accessible.
3. Celebrity Merge: Merges the precomputed candidate list with the celebrity tweet streams using an in-memory multi-way merge ($O(C \log S)$ where $C$ is the total candidate items consumed, roughly 300 items, and $S$ is the number of sorted candidate streams).
4. Retweet Deduplication: Identifies duplicate entries where a user received both the original tweet and a retweet of that same tweet, collapsing them into a single entry displaying a retweet attribution badge.
5. Ranking: Passes the consolidated candidate pool through the ML Ranking Service to score tweets by engagement velocity and author affinity (or sorts strictly by timestamp if the user selected the chronological "Latest Tweets" view).
6. Hydration: Extracts only the top 20 candidate tweet IDs for the requested page and hydrates full tweet metadata, media URLs, real-time like/retweet counts, and author profiles from the Redis Tweet Cache (falling back to authoritative Cassandra records on cache miss).
7. Response Assembly: Attaches pagination cursors and returns the final payload to the client. Under normal healthy warm-cache conditions with local network hops, this in-process pipeline executes within an illustrative ~12 to 15 ms internal serving budget, comfortably meeting our formal production SLO of p99 < 200 ms.

Fan-Out Service

The Fan-Out Service operates as a scalable Kafka consumer group dedicated to timeline distribution.

For each incoming tweet, the worker checks the author's follower count against the 10,000 threshold. Below the threshold, it fetches the follower list from the Social Graph Service and performs pipelined ZADDoperations into each follower's Redis timeline sorted set. For accounts at or above the threshold, push fan-out is skipped, and the tweet ID is recorded in the author's recent tweet cache in Redis.

Because Kafka provides at-least-once delivery, fan-out workers must be idempotent. Redis ZADD is naturally idempotent when scoring by tweet ID timestamp, ensuring network retries do not produce duplicate entries. The same worker fleet handles deletions (executing ZREM across follower timelines) and retweet distributions.

List Feed Architecture

List feeds represent curated subsets of creators and follow a distinct fan-out model separate from follower feeds.

The architecture explicitly separates list members (creators in the list) from list subscribers (users following the list). The system maintains a single precomputed timeline sorted set in Redis keyed by list ID (timeline:list:{list_id}). When a creator tweets, the Fan-Out Service queries a reverse membership index (mapping creator ID to list IDs containing that creator) and pushes the tweet ID into those list timeline caches.

Because the list timeline is precomputed once per list, having millions of list subscribers generates zero subscriber-proportional write amplification on tweet creation. Fan-out occurs once per list containing the creator rather than once per subscriber, and subscribers simply read that single precomputed list cache. If an individual creator is an extreme outlier included in tens of thousands of lists, the system uses the creator-to-list reverse membership index to pull that creator's tweets on read into list views rather than pushing to every list cache.

Social Graph Service & Follow Lifecycle

The Social Graph Service manages relationships and handles follow, unfollow, and refollow transitions.

• Follow Event: When User A follows User B, the service executes a bounded backfill, inserting the latest 20 to 50 tweets from User B into User A's home timeline cache in Redis.
• Refollow Event: If User A unfollowed and later refollows User B, the same bounded backfill executes rather than resurrecting arbitrarily stale historical entries.
• Unfollow Event: Handled via lazy deletion. The user's follow set is cached in Redis with a short TTL. When the timeline is assembled at read time, tweets from unfollowed accounts are filtered out during candidate evaluation, while a background compaction job cleans up aged entries.
• Block Event: Triggers an immediate read-time filter and enqueues an asynchronous task to purge the blocked user's tweets from the cache.

Search Service and Elasticsearch

Near-real-time search indexing keeps recent tweets discoverable within seconds of publication.

The Search Indexer consumes tweet-events asynchronously and indexes documents into an Elasticsearch cluster. Each indexed document includes the tweet ID, author ID, content, hashtags, mentions, creation timestamp, and initial engagement signals. At query time, BM25 text relevance is combined with recency decay and engagement boosts to rank search results. Full inverted index architectures are explored in Search Engine.

Trending Topics

Velocity-based hashtag tracking is decoupled into a dedicated stream-processing pipeline.

The core timeline architecture publishes raw tweet events to Kafka, allowing a downstream streaming cluster (such as Apache Flink using sliding windows and Count-Min Sketch) to compute trending hashtags per geographical region. The complete streaming architecture is covered in Trending Topics.

Notification Service

Notifications are fully asynchronous and never sit on the critical path of tweet creation.

A dedicated consumer group listens to tweet-events, like-events, and follow-eventsto dispatch mobile push alerts via Apple APNs and Google FCM. Similar events are aggregated into digest notifications (such as "Alice and 15 others liked your tweet") to prevent notification storms during viral surges.

ML Ranking Service

The home timeline applies machine-learning models to rank candidate tweets for user engagement.

After candidate generation produces roughly 300 candidate tweet IDs, a lightweight gradient-boosted decision tree scores each tweet by recency decay, author affinity, engagement velocity (likes, retweets, replies), content media type, and verification status. The scoring stage executes in under 10 ms for a candidate batch. If the ranking service experiences degradation, the Timeline Service falls back to chronological sorting.

Analytics Pipeline

Analytics pipelines operate on independent SLAs separate from timeline serving.

Apache Flink processes tweet-events, like-events, and follow-events, streaming aggregated engagement metrics into ClickHouse for creator analytics dashboards and offline model feature stores.

Event Bus Design (Kafka)

The event bus decouples write ingestion from fan-out workers and background indexers.

Topic Architecture and Consumer Groups:

Topics:
  tweet-events:       New tweet creations, deletions, native retweets, and quote tweets
  like-events:        Like and unlike actions on tweets
  follow-events:      Follow and unfollow graph mutations
  mention-events:     User mention notifications and alerts

Producer Configuration:
  - tweet-events: Driven by Cassandra CDC connector tailing committed on-disk CommitLog mutations
  - like-events, follow-events, mention-events: Published by their respective owning services (Interaction Service, Social Graph Service) using reliable transactional outbox/CDC publication mechanisms

Topic Configuration (tweet-events):
  Partitions: 128
  Partition key: author_id (ensures ordered event processing per author across partition workers)
  Retention: 7 days
  Replication factor: 3, min.insync.replicas: 2

Consumer Groups:
  1. fan-out-worker:   Pushes tweet_id via ZADD to follower Redis home timelines (< 10K followers)
  2. list-fanout:      Pushes tweet_id to list timeline caches for lists containing the creator
  3. search-indexer:   Indexes tweet documents into Elasticsearch cluster
  4. notification:     Dispatches push notifications for mentions, replies, and retweets via APNs and FCM
  5. analytics:        Streams engagement events through Flink to ClickHouse

Synchronous Ingress Path:
  Validate payload -> Append tweet record to authoritative Cassandra store -> Return HTTP 201 Created

Asynchronous Event Pipeline:
  Cassandra CDC connector reads committed CommitLog mutations from disk -> Publishes event to tweet-events in Kafka -> Downstream consumer groups execute fan-out, search indexing, and push alerts without blocking the tweet creation path.
  Dead Letter Queue: tweet-events-dlq triggered after 3 retries, with alerts when consumer lag exceeds 60 seconds.