The system should support millions of concurrent users, generate feeds with low latency, and scale to billions of tweets.
The platform should also support interactions such as likes, retweets, and notifications while remaining highly available and horizontally scalable.
Requirements
Functional Requirements
The Twitter (X) system should satisfy the following functional requirements.1. Allow users to publish tweets.
2. Allow users to follow and unfollow other users.
3. View a personalized home timeline.
4. View a user's timeline.
5. Like and retweet tweets.
6. Search tweets.
7. Send notifications for relevant user activities.
Non-Functional Requirements
The system should also satisfy the following non-functional requirements.1. Low latency.
2. High availability.
3. Horizontal scalability.
4. High read throughput.
5. Fault tolerance.
6. Support billions of tweets.
API Design
The Twitter (X) platform can expose REST APIs for publishing tweets, managing followers, retrieving timelines, and interacting with tweets.Post Tweet
Request:POST /api/v1/tweets
{
"content": "Designing scalable systems is all about choosing the right trade-offs."
}{
"tweetId": "T123456",
"status": "CREATED"
}Follow User
Request:POST /api/v1/users/U101/follow
{
"userId": "U205"
}{
"status": "FOLLOWING"
}Home Timeline
Request:GET /api/v1/timeline/home?limit=20{
"tweets": [
{
"tweetId": "T1001",
"userId": "U205",
"content": "Building distributed systems...",
"createdAt": "2026-08-09T10:00:00Z"
}
],
"nextCursor": "cursor_123"
}User Timeline
Request:GET /api/v1/users/U205/timeline?limit=20Like Tweet
Request:POST /api/v1/tweets/T123456/like{
"status": "LIKED"
}High-Level Architecture
The following diagram illustrates the high-level architecture of a Twitter (X)-like social media platform.
API Gateway
The API Gateway acts as the single entry point for client applications.It authenticates requests, validates input, applies rate limiting, and routes requests to the appropriate backend service.
For example, a tweet creation request is routed to the Tweet Service, while a home timeline request is routed to the Timeline Service.
The API Gateway also hides the internal topology of backend services from client applications.
User Service
The User Service manages user accounts, authentication information, profiles, and follow relationships between users.A relational database such as PostgreSQL is suitable because user accounts and follow relationships require transactional consistency.
The User Service maintains two primary tables: USERS and FOLLOWS.
Users
USERS
--------------------------------------------------------------------------------
user_id | username | email | created_at
--------------------------------------------------------------------------------
U101 | amit | amit@example.com | 2026-01-10
U205 | rahul | rahul@example.com | 2026-02-15
U310 | priya | priya@example.com | 2026-03-21
Follows
FOLLOWS
---------------------------------------------
follower_id | following_id | created_at
---------------------------------------------
U101 | U205 | 2026-08-01
U101 | U310 | 2026-08-02
U205 | U310 | 2026-08-03
When a user follows or unfollows another user, the User Service updates this relationship in PostgreSQL.
Frequently accessed follow relationships can also be cached in Redis to reduce repeated database reads during timeline generation.
Tweet Service
The Tweet Service is responsible for creating and retrieving tweets.Tweets are typically stored in a distributed NoSQL database such as Cassandra because the system must support billions of tweets and very high write throughput.
Tweets can be partitioned using userId so that a user's tweets are stored together. A simplified schema can look like:
CREATE TABLE tweets (
user_id TEXT,
created_at TIMESTAMP,
tweet_id TEXT,
content TEXT
PRIMARY KEY ((user_id), created_at)
);
The database can distribute different users across multiple nodes, allowing tweet storage to scale horizontally.
After the tweet is successfully stored, the Tweet Service publishes a TweetCreated event to Kafka.
The tweet creation request does not wait for timeline generation, search indexing, analytics, or notifications.
This keeps the critical tweet creation path short and allows those operations to be processed asynchronously.
Timeline Service
The Timeline Service is responsible for generating and serving personalized home timelines. A user's home timeline contains tweets from users that the current user follows.There are two common approaches to generating the timeline: Fan-Out on Write and Fan-Out on Read.
Fan-Out on Write
With Fan-Out on Write, when a user creates a tweet, the system identifies the user's followers and copies a reference to the tweet into each follower's timeline.For example: When User A has 100 followers, the system writes the tweet reference into 100 timeline entries.
This increases write traffic but makes timeline reads extremely fast because the timeline is already precomputed. Recent timelines can be stored in Redis for very fast access.
Fan-Out on Read
With Fan-Out on Read, tweets are stored only once.When a user opens the home timeline, the Timeline Service retrieves the users they follow and fetches their recent tweets. The tweets are then merged and sorted by creation time.
This approach reduces write amplification but increases read latency and database work.
Hybrid Approach
In a large-scale Twitter-like system, a hybrid approach can be used. For normal users, Fan-Out on Write provides fast timeline reads.For celebrity or high-follower accounts, Fan-Out on Read avoids copying a tweet into millions of timeline entries.
For example, if a celebrity has millions of followers, copying every tweet into every follower's timeline would create a massive write workload.
Instead, celebrity tweets can be stored once and merged into timelines when followers request their home feed.
Likes & Retweets
The Like/Retweet Service manages user interactions with tweets, including likes, unlikes, retweets, and undoing retweets.These interactions should be stored separately from the main tweet record because the system needs to maintain information about which user performed the action, which tweet was affected, and when the interaction occurred.
A separate database such as Cassandra can be used because likes and retweets can generate extremely large amounts of data and require horizontal scalability.
CREATE TABLE likes (
tweet_id TEXT,
user_id TEXT,
created_at TIMESTAMP,
PRIMARY KEY ((tweet_id), created_at)
);
Similarly, retweets can be stored separately:
CREATE TABLE retweets (
tweet_id TEXT,
created_at TIMESTAMP,
user_id TEXT,
PRIMARY KEY ((tweet_id), created_at)
) WITH CLUSTERING ORDER BY (created_at DESC);
For example:
tweet:T1001:likes → 152340
tweet:T1001:retweets → 28450
Search
Tweets can be indexed in a search engine such as Elasticsearch. Tweet creation does not need to synchronously update the search index.Instead, the Tweet Service publishes the tweet event to Kafka. The Search Service consumes the event and indexes the tweet asynchronously.
This keeps search indexing separate from the critical tweet creation path.
If Elasticsearch becomes temporarily unavailable, the tweet remains safely stored in Cassandra and the Kafka event can be processed again after the search service recovers.
Media Storage
Images and videos should not be stored directly inside the tweet database. The client uploads media to Object Storage.The Object Storage service returns a media URL or identifier. The tweet then stores only the media metadata and URL.
Media files can be delivered through a CDN so that users can download images and videos from geographically closer edge locations.
High Availability
The Twitter (X) platform must remain available even when individual servers or infrastructure components fail.Multiple instances of stateless services run behind a Load Balancer. If one service instance fails, traffic is automatically routed to another healthy instance.
Critical infrastructure such as Redis, Cassandra, and Kafka is deployed with replication.
Redis can also be deployed as a cluster with replicas and automatic failover.
If an entire service instance fails during timeline generation, the timeline can be rebuilt from the underlying data.
Scalability
The application layer scales horizontally by adding additional instances of services such as the API Gateway, Tweet Service, Timeline Service, Follow Service, Search Service, and Notification Service.Because these services are largely stateless, additional instances can be added without changing application logic.
Tweets are distributed across multiple Cassandra nodes using userId as the partition key.
As the number of tweets grows into billions, additional database nodes can be added to increase storage and write capacity.
Conclusion
A Twitter (X)-like platform appears simple from the user's perspective, but supporting millions of concurrent users and billions of tweets requires careful handling of high write throughput.The critical design is to use Fan-Out on Write for normal users, combined with Fan-Out on Read for celebrity accounts.
This hybrid approach provides low-latency timeline reads while avoiding the massive write amplification that would occur if tweets from high-follower accounts were copied into millions of timelines.
