System requirements

Functional:

List functional requirements for the system (Ask the chat bot for hints if stuck.)...

1. Nested Structure: The system should support 2 levels of nesting where users can reply to comments in a hierarchical structure. The nested comment should be no longer than 2 levels.
2. Real-Time Updates: Users should be able to view new comments and replies in real-time without the need for manual refreshing.
3. Order Preservation: The system should maintain the order of comments and replies within each thread to ensure the chronological flow of the conversation.
4. Moderation: The system should include features for moderating comments, such as deleting inappropriate comments and editing their own comments
5. User Engagement: It should allow users to interact with comments, user should be able to click on specific buttons to upvote or downvote a comment.
6. Authentication and Authorization: Users should be able to authenticate themselves and the system should enforce appropriate access controls.
7. Data Retention: The system should retain 3 years worth of comments.
8. Users should be able to sort the comments by time or popularity.

Non-Functional:

List non-functional requirements for the system...

1. Scalability: The system should be able to handle a large number of concurrent users and comments efficiently.
2. Responsive Design: The system should provide a seamless user experience across various devices, such as desktops, tablets, and mobile phones.
3. Low latency: The end to end response time for posting / loading comments should be sub-second.
4. High availability: The system should be available for at least 99.5% of time.
5. Data consistency: The system should maintain high consistency, so that users will not be confused by late reply / votecount.

API design

Define what APIs are expected from the system...

• POST /comment
  • request:
    • content(string)
    • topic_id
    • parent_id
  • response:
    • status: (success / fail)
    • comment object
      • id: (comment_id)
      • content (string)
      • poster_id (id of user posting the coment)
      • poster_display_name (string)
      • timestamp
• GET /{topic_id}/comments?last_timstamp={last_timestamp}&size={page_size}
  • response:
    • status: (success / fail)
    • topic_id
    • topic_title
    • created_at
    • comments
      • id
      • content
      • poster_id
      • poster_display_name
      • commented_at (timestamp)
      • replied_to (id of the comment that this replies to)
      • upvote_count
      • downvote_count
• POST /comment/{topic_id}/{comment_id}/reply
  • request:
    • content
  • response:
    • status
    • comment
      • id
      • content
      • poster_id
      • poster_display_name
      • commented_at
      • replied_to
• PUT /comment/{comment_id}/upvote
  • response
    • status
• PUT /comment/{comment_id}/downvote
  • response
    • status
• DELETE /admin/{comment_id}
  • response
    • status
• GET /comments/{topic_id}/{comment_id}/replies
  • response
    • list of
      • id
      • content
      • poster_id
      • poster_display_name
      • commented_at
      • replied_to
      • parent_id
      • topic_id

High-level design

You should identify enough components that are needed to solve the actual problem from end to end. Also remember to draw a block diagram using the diagramming tool to augment your design. If you are unfamiliar with the tool, you can simply describe your design to the chat bot and ask it to generate a starter diagram for you to modify...

The system should include the following items:

Client (Publisher + Receiver): The client plays two different roles in the system: comment publishers and comment receivers.

Servers (Dispatcher + Gateway Server): The servers play two roles in the system: the dispatcher broadcasts the comments to appropriate servers (and subsequently receivers), and the Gateway Server forwards them to the receivers.

Storage (Endpoint Store + comments store + in-memory subscription store): The system has three storage locations—the comment store stores comments, user information, etc. The Endpoint Store contains information on which gateway servers are subscribed to what topics. The In-memory subscription store resides in the Gateway Server and contains information on which receivers want to receive comments on which topics.

Client: Let's call normal read path handler client - client

Read Server: Handles read path, will read comments from comments store and returns to client, also update endpoint store and gateway server as needed

Here's the way to handle Create, Update and Delete (Write Path)

Because these operations mutate state and require live updates to other users, they follow the entire flowchart.

1. API Call: The client sends a POST, PATCH, or DELETE request as the Publisher.
2. Orchestration: The Publisher forwards the event to the Dispatcher.
3. Business Logic & Persistence: The Dispatcher handles the structural logic:
   • For Create: It verifies the topic_idexists, calculates the new nested path, and inserts the record into the Comments Store.
   • For Update: It checks authorization, modifies the text, flags it as is_edited, and updates the Comments Store.
   • For Delete: It performs a "soft delete" (masking the content but keeping the node intact so child comments don't break) in the Comments Store.
4. Routing the Live Update: * The Dispatcher queries the Endpoint Store to find out which routing paths or regions care about thread_id: 123.
   • It broadcasts a lightweight event (e.g., COMMENT_ADDED or COMMENT_DELETED) to the appropriate Gateway Server.
5. Delivery: The Gateway Server pushes the event down the active WebSocket connection to the Receivers (the clients viewing the page), instantly updating their UI.

Retrieve (R) - The Read Path

This architecture is heavily optimized for writes and real-time pushes. For standard Retrieve operations (e.g., a user loads the page for the first time), the flow is slightly different:

• Initial Page Load: The client typically skips the Dispatcher entirely. It sends a GET request to a Read API (which could sit alongside or within the Publisher block) that queries the Comments Store (or a Redis cache sitting in front of it) directly to fetch the paginated, nested comment tree.
• Subsequent Reads: Once the initial tree is loaded, the client establishes a connection with the Gateway Server to receive all future updates in real-time.

To handle pagination, we need to use cursor-based pagination. Specifically, the initial comments will return the first page and a cursor, and subsequently when user scroll or move to next page, cursor is used to fetch subsequent pages.

To handle lazy-loading of nested comments, the client can send a request to the GET /comments/{topic_id}/{comment_id}/replies API, and the server reads from the comments store and returns the list. Besides, the server also updates the Gateway Server and the Endpoint Store to subscribe to the newly loaded reply path.

Real-time-notification: Once a client read a specific thread, or a specific reply with replies, they subscribe to this topic via websocket or server-side events. Whenever a new reply is available, the dispatcher will read subscriptions from endpoint store, figure out what gateway server needs it, and then the gateway server will forward the update through server-side events to the interested receivers.

API-gateway: This gateway handles authentication of users. It verifies that the user is logged in and also have enough permission to read / post in certain threads. Once that's done, it forwards these information to dispather or read server to further handles the requests.

Detailed component design

Dig deeper into 2-3 components and explain in detail how they work. For example, how well does each component scale? Any relevant algorithm or data structure you like to use for a component? Also you could draw a diagram using the diagramming tool to enhance your design...

Gateway Server: In order to achieve real-time comments refresh, each gateway server maintains SSE connections to all receiving clients. Each server also contains an in-memory subscription store, so that it does not fan out comments to all receivers unnecessarily.

Endpoint Store: This storage is stand-alone so that dispatchers does not need to maintain a state, therefore, the publishing load can be flexibly distributed across all dispatchers.

Database design

Defining the system data model early on will clarify how data will flow among different components of the system. Also you could draw an ER diagram using the diagramming tool to enhance your design...

Topics Table

• topic_id - string
• title - string
• created_at - timestamp

Comments Table

• comment_id
• topic_id - foreign key, id of the topic this comment belongs to
• poster_id - foreign key of user table.
• replied_to - optional, id of the comment that this comment replies to, if applicable
• commented_at - timestamp
• upvote_count
• downvote_count

Users Table

• user_id
• user_display_name
• role

Upvotes Table

• user_id
• comment_id

Downvotes Table

• user_id
• comment_id