System Requirements

Functional Requirements:

1. Users can post top-level comments on a resource (e.g., a video or article).
2. Users can reply to existing comments, creating a nested hierarchy.
3. Users can view comments and their replies (paginated).
4. Users should see real-time updates when new comments are posted while they are viewing the page.

Non-Functional Requirements:

1. High Scalability: The system must handle massive read loads (e.g., viral videos) and sudden write spikes.
2. Low Latency: Comment loading and posting should feel instantaneous.
3. High Availability: The ability to read comments should degrade gracefully if write systems are under heavy load.

API Design

To ensure the APIs are RESTful, we separate the actions of fetching top-level comments from fetching replies. We also utilize your cursor-based pagination strategy using the TimeUUID.

1. Create a Top-Level Comment POST /v1/videos/{video_id}/comments

JSON

2. Reply to a Comment POST /v1/comments/{parent_id}/replies

JSON

3. Fetch Top-Level Comments (Cursor Paginated) GET /v1/videos/{video_id}/comments?limit=20&cursor={time_uuid} Returns a list of comments. The client uses the commentId of the last item as the cursor for the next request.

4. Fetch Replies for a Comment (Lazy Loading) GET /v1/comments/{parent_id}/replies?limit=10&cursor={time_uuid}

High-Level Design

1. Client: Makes requests to load the video and comments. Establishes a WebSocket connection for real-time updates.
2. API Gateway / Load Balancer: Routes HTTP traffic to the Comment Service and WebSocket traffic to the Real-Time Notification Service.
3. Comment Service: The core backend application that handles the business logic of validating, saving, and retrieving comments.
4. Primary Database: Stores the comment data using your proposed Adjacency List pattern.
5. Cache (Redis): Caches the top-level comments for highly popular videos to protect the database from read spikes.
6. Message Broker (Kafka / Redis PubSub): When a new comment is saved, an event is published here.
7. Real-Time Service (WebSocket Servers): Listens to the message broker and pushes the new comment payload down to any connected clients currently watching that specific video thread.

Detailed Component Design

Let's dig into the core mechanics that make your proposed solution scale.

1. TimeUUID & Cursor-Based Pagination Your choice of TimeUUID (UUIDv1 or UUIDv7) as the primary key is the linchpin of this design. Because the timestamp is embedded within the ID, the database inherently stores the comments in chronological order. When a user clicks "Load More", the SQL query simply becomes: SELECT * FROM comments WHERE parentId = X AND commentId < {cursor} ORDER BY commentId DESC LIMIT 10; This avoids the massive performance hits of OFFSET pagination on large tables.

2. Real-Time Updates (Pub/Sub & WebSockets) To satisfy the real-time requirement without the client spamming the server with pull requests, we use a push model.

• When a user opens a video, they open a WebSocket connection and "subscribe" to a topic named video_{video_id}.
• When someone posts a comment, the backend saves it to the DB and publishes a message to a Redis Pub/Sub channel or Kafka topic.
• The WebSocket servers consume this message and broadcast the new comment JSON to all active connections subscribed to that video.