Design Real-Time Comments with Optimistic Updates

Real-Time Optimistic Comment System

We design a comment system that gives users immediate visual feedback (optimistic posting) while ensuring consistency and durability. The system must handle temporary identities, idempotent creation, response/event reconciliation, failure recovery, and live synchronization across multiple clients.

---

1. High-Level Architecture

• Client: Web/mobile app. Generates a temporary ID per comment, renders it optimistically in a “pending” state, and manages retries.
• Real-Time Layer: WebSocket connection per user session (or per document/thread). Used for broadcasting new comments, edits, and status changes to all connected clients.
• REST API: Standard HTTP endpoints for posting a new comment (POST /comments), fetching history (GET /comments?page=...), and optional update/delete.
• Database: Stores comments persistently. Schema includes at minimum: id (server-generated, UUID or snowflake), thread_id, author_id, content, created_at, idempotency_key (client‑supplied temporary ID), and status (active, hidden, deleted).
• Cache/Message Broker: Optional Redis pub/sub for fanning out live events from the write path to all WebSocket servers.

---

2. Temporary Identities & Idempotent Creation

• Temporary ID: Before sending the POST, the client creates a UUIDv4 and prefixes it with temp- (e.g., temp-4a7d1ed5-...). This is the idempotency key.
• Idempotency on the server: The server treats the temporary ID as a unique business key. On receipt, it first checks if a comment with that key already exists (e.g., in a dedicated idempotency‑key table or a unique index on the comment table).
  • If not present: insert the new comment with the real server ID and mark the key as consumed. Return 201 Created with the real ID, created_at, and any moderating status.
  • If already present: return 200 OK with the existing comment data (real ID, timestamp, etc.). This handles retries safely, even if the original response was lost.
• Why not client‑determined ordering? Temporary IDs are not used for ordering—the server’s created_at or a monotonic id determines the canonical order once acknowledged.

---

3. Optimistic Posting Flow

1. User submits comment → client creates a temporary ID.
2. Client optimistically appends a new entry to the local comment list:

   {
     "id": "temp-...",
     "content": "...",
     "author": "...",
     "createdAt": "now (client‑side)",
     "status": "pending"
   }
   

   The UI renders it immediately, maybe with a faint “Sending…” indicator.
3. Client sends POST /comments with body:

   {
     "thread_id": "...",
     "content": "...",
     "idempotency_key": "temp-..."
   }
   

4. While awaiting the response, the UI allows further interaction (scrolling, reading, even posting another comment). No blocking spinner.

---

4. Reconciliation with the Server Response

When the POST promise resolves (or times out), the client reconciles the optimistic comment:

• 201 success:
  1. Locate the pending comment by idempotency_key.
  2. Replace the temporary ID with the real server ID.
  3. Update createdAt to the server timestamp (may cause the comment to shift position in a chronologically sorted list).
  4. Set status to "posted" (or "pending_moderation" if content goes through a pipeline).
  5. Remove any “retry” indicators.
• 409 Conflict or duplicate: The server returns the already‑created comment (because idempotency key consumed). Treat identically to a 201; the client may not have known the comment succeeded earlier (e.g., due to a lost response). Reconcile the same way.
• 400 Bad Request (e.g., validation failure, spam):
  1. Mark the pending comment as status = "error" with the server’s error message.
  2. Give the user the ability to edit the content and retry. On retry, the client must generate a new temporary ID because the old one is permanently invalid for this content. (Alternatively, the server could allow idempotency‑key reuse only for retries that carry the same content; but that complicates the server logic and is less robust against changes.)
• Network timeout (no response):
  1. Keep status = "pending". Display an “Uploading…” indicator with an option to manually retry.
  2. The client retries automatically with exponential backoff (e.g., 1s, 2s, 4s, up to 30s) using the same temporary ID. Because the POST is idempotent, the server will either create the comment once or return the already‑created one. The client re‑reconciles on each response until successful.

---

5. Handling Real-Time Events and Race Conditions

• WebSocket channel: After the server creates a comment (or marks it as received), it broadcasts a "new_comment" event to all subscribers of the thread, including the original poster. The event payload contains the real ID, content, author, timestamp, and the idempotency_key (if supplied) for client deduplication.
• Race: Live event arrives before POST response
  The client listens on the WebSocket. When a new_comment event arrives:
  1. Check if event.idempotency_key matches any pending comment’s temp ID.
  2. If yes, treat the event as the authoritative acknowledgement: remove the pending state, replace the temp ID with the real ID, set the server timestamp, and stop waiting for the POST response (ignore the subsequent HTTP response if it arrives later, as the comment is already reconciled).
  3. If no matching temp ID, it’s from another user – append it to the list as a normal comment, but deduplicate with any existing real IDs to avoid double rendering.
• Race: POST response arrives before the live event
  Reconciliation already happened; when the same new_comment event later arrives (since the server broadcasts to all, including the poster), the client must recognise the real ID already exists in its local list – skip it.
• Consistency across tabs/devices: The optimistic comment is visible only in the client where it was submitted. Other clients see the comment only after the server processes and broadcasts it. This is acceptable; the submitting user enjoys immediate feedback, but cross‑device consistency is not required for optimistic drafts.

---

6. Error States & Retry Behavior

• Visible failure states (as described above):
  • Pending: faint, editable, cancelable.
  • Error: highlighted with error message, “Retry” and “Discard” buttons.
  • Posted: normal styling.
• Retry strategy:
  • Automatic for timeouts (5xx, network errors) with exponential backoff.
  • Manual retry for 4xx validation failures.
  • On retry for timeouts, reuse the same idempotency key.
  • If the client navigates away while pending, the optimistic comment is lost from memory. Upon return, the client could re‑fetch the thread; if the server had accepted the comment before the navigation, it will appear in the history (with real ID). To improve UX, the client could persist pending drafts in localStorage and re‑apply them after a page reload, but this is optional.
• Server rejection (e.g., forbidden words): The error state gives the user a chance to edit the content. When they tap “Retry” after editing, the client creates a new temporary ID and re‑posts, because the previous idempotency key is now associated with a rejected (and never persisted) attempt and cannot be reused without risking ignoring a new, corrected comment.

---

7. Durable History & Multi‑Device Sync

• History loading: On first opening a thread, the client fetches the most recent N comments via GET /comments?thread_id=...&before=<cursor> paginated by created_at and optionally monitor‑friendly. All comments in the history are in canonical order.
• Ordering guarantees:
  • Comments are sorted chronologically by created_at (server timestamp).
  • Pending comments inserted optimistically by the local client use a client‑side timestamp that may be out of order once the server timestamp replaces it. The list may momentarily “shuffle” when the real timestamp is applied. This is acceptable for a real‑time feed; the alternative (inserting optimistically at top or bottom regardless of time) could also work depending on UX requirements.
• Multi‑device consistency: The same user on two devices will see the final accepted comments identically (both capture the same live events). A pending comment on device A is not visible on device B until it is processed. If the user posts from device A and the POST succeeds, device B receives the broadcast and shows the comment normally.

---

8. Clarifying Questions Addressed

Can comments be edited or deleted?
Yes. Editing and deletion can also be optimistic:

• Edit: client sends PATCH /comments/:id with new content and an updated timestamp. Optimistically update the local comment; on failure, revert. Idempotency can be achieved by including a version or last_modified header, but simpler: use a new idempotency key for each edit if needed.
• Delete: send DELETE /comments/:id; optimistically remove the comment from the list (or grey it out). On failure, restore.

How are comments ordered?
Primarily by server‑generated created_at (with sub‑millisecond precision or tie‑breaking by a monotonic ID). Client‑side pending comments are inserted near the top or bottom with a placeholder timestamp; they are reordered when the real timestamp arrives.

Timeout with unknown commit outcome?
Retry with the same idempotency key. Because the server deduplicates, this is safe. The client continues to show the comment as pending until a definitive response (success or server rejection) arrives.

Must another device see the same conversation?
Yes, but only after the server has accepted and persisted the comments. Optimistic drafts are local and invisible to others; this is by design.

---

9. Follow‑Up Questions

What if a live event arrives before the POST response?
As described in §5, the client uses the idempotency key from the WebSocket event to reconcile the pending comment immediately, ignoring the (now redundant) HTTP response.

How do you avoid duplicate comments on retry?
Idempotency keys on the server guarantee that the same logical comment is never created twice. The server must atomically check and insert using a unique constraint on (thread_id, idempotency_key).

What if the server rejects content (spam/validation)?
The client enters an error state, allowing the user to edit and resubmit. When resubmitting after a hard rejection, a new temporary ID must be generated so that the corrected content is treated as a brand‑new attempt, not a duplicate of the rejected one.

What if the user navigates away?
Pending optimistic comments are lost from the current page. The comment may still be accepted by the server (if the POST was already in flight). When the user returns, the comment will appear in the history if the POST succeeded. To improve the experience, the client could show a confirmation dialog if there are unsent changes, and/or persist pending drafts to localStorage and re‑apply them on page load with a flag indicating they need to be synced (re‑POST if the server did not receive them). However, this adds complexity; a minimal robust design simply discards unsent drafts and relies on the server’s eventual consistency for in‑flight posts.

---

This design balances immediate user feedback with system integrity, leverages idempotency to handle network unreliability, and reconciles optimistic state with both HTTP responses and real‑time events to avoid inconsistencies.