System Design #8: Design a Nested Comments System

interface NestedComment {
  id: string;
  content: string;
  children: NestedComment[]; // Recursive
}
// Problem: Updating a deeply nested comment requires deep cloning
// Problem: React can't efficiently diff deep trees
// Problem: Normalization is painful

interface Comment {
  id: string;
  parentId: string | null;
  content: string;
  authorId: string;
  depth: number;
  childCount: number;
  createdAt: string;
}

// Store as a flat normalized map
interface CommentsState {
  byId: Record<string, Comment>;
  rootIds: string[];          // Top-level comment IDs in sort order
  childrenMap: Record<string, string[]>; // parentId → sorted child IDs
  collapsedIds: Set<string>; // Which threads are collapsed
}

CommentsSection
├── CommentSortBar          // Sort controls
├── CommentComposer         // Top-level "Add comment" form
├── CommentThread           // Recursive renderer
│   ├── CommentNode         // Single comment
│   │   ├── CommentContent  // Rendered markdown/text
│   │   ├── CommentActions  // Like, Reply, Edit, Delete
│   │   └── ReplyComposer   // Inline reply form (toggled)
│   ├── CollapseToggle      // [−] / [+] thread toggle
│   └── CommentThread[]     // Recursive children
└── LoadMoreButton          // "Show 42 more replies"

function flattenVisibleComments(
  state: CommentsState,
  maxDepth: number = 10
): FlatComment[] {
  const result: FlatComment[] = [];
  
  function walk(id: string, depth: number) {
    const comment = state.byId[id];
    if (!comment) return;
    
    result.push({ ...comment, depth, isCollapsed: state.collapsedIds.has(id) });
    
    // Don't recurse into collapsed threads
    if (state.collapsedIds.has(id)) return;
    
    // Don't recurse beyond max depth (show "Continue thread →")
    if (depth >= maxDepth) return;
    
    const children = state.childrenMap[id] || [];
    for (const childId of children) {
      walk(childId, depth + 1);
    }
  }
  
  for (const rootId of state.rootIds) {
    walk(rootId, 0);
  }
  
  return result;
}

// Render with indentation via margin-left
{flatList.map(comment => (
  <div key={comment.id} style={{ marginLeft: comment.depth * 24 }}>
    <CommentNode comment={comment} />
  </div>
))}

interface CommentResponse {
  id: string;
  parent_id: string | null;
  content: string;
  author: {
    id: string;
    username: string;
    avatar_url: string;
  };
  likes_count: number;
  dislikes_count: number;
  child_count: number;       // Total descendants (for "N replies" label)
  depth: number;             // Server-computed for validation
  created_at: string;
  updated_at: string;
  is_edited: boolean;
  user_vote: 'like' | 'dislike' | null; // Current user's vote
}

// API returns paginated flat list, client builds the tree
interface CommentsPageResponse {
  comments: CommentResponse[];
  total_count: number;
  has_more: boolean;
  cursor: string;            // For cursor-based pagination
}

interface OptimisticComment extends Comment {
  _optimistic: true;
  _tempId: string;     // Client-generated UUID
  _status: 'pending' | 'confirmed' | 'failed';
}

function addOptimisticComment(state: CommentsState, draft: CommentDraft): CommentsState {
  const tempId = crypto.randomUUID();
  const optimistic: OptimisticComment = {
    id: tempId,
    _tempId: tempId,
    _optimistic: true,
    _status: 'pending',
    parentId: draft.parentId,
    content: draft.content,
    authorId: currentUser.id,
    depth: draft.parentId ? state.byId[draft.parentId].depth + 1 : 0,
    childCount: 0,
    createdAt: new Date().toISOString(),
  };
  
  return {
    ...state,
    byId: { ...state.byId, [tempId]: optimistic },
    rootIds: draft.parentId ? state.rootIds : [tempId, ...state.rootIds],
    childrenMap: draft.parentId
      ? { ...state.childrenMap, [draft.parentId]: [tempId, ...(state.childrenMap[draft.parentId] || [])] }
      : state.childrenMap,
  };
}

// On server confirmation: swap tempId → real ID
function confirmComment(state: CommentsState, tempId: string, realComment: Comment): CommentsState {
  const newById = { ...state.byId };
  delete newById[tempId];
  newById[realComment.id] = realComment;
  
  // Update all references from tempId to realId
  const updateRefs = (ids: string[]) => ids.map(id => id === tempId ? realComment.id : id);
  
  return {
    ...state,
    byId: newById,
    rootIds: updateRefs(state.rootIds),
    childrenMap: Object.fromEntries(
      Object.entries(state.childrenMap).map(([k, v]) => [
        k === tempId ? realComment.id : k,
        updateRefs(v)
      ])
    ),
  };
}

// GET /api/comments?post_id={id}&sort={sort}&cursor={cursor}&limit=20
// Returns: CommentsPageResponse (flat list, sorted)

// GET /api/comments/{id}/replies?cursor={cursor}&limit=10
// Returns: CommentsPageResponse (children of a specific comment)

// POST /api/comments
// Body: { post_id, parent_id?, content }
// Returns: CommentResponse

// PATCH /api/comments/{id}
// Body: { content }
// Returns: CommentResponse

// DELETE /api/comments/{id}
// Returns: 204 (soft delete — shows "[deleted]")

// POST /api/comments/{id}/vote
// Body: { type: "like" | "dislike" | "none" }
// Returns: { likes_count, dislikes_count }

// Subscribe to comment changes via WebSocket/SSE
interface CommentEvent {
  type: 'new_comment' | 'edit_comment' | 'delete_comment' | 'vote_update';
  comment: CommentResponse;
  post_id: string;
}

// Handle real-time inserts without disrupting scroll
function handleNewComment(event: CommentEvent, state: CommentsState): CommentsState {
  // Don't insert if it's our own optimistic comment
  if (state.byId[event.comment.id]) return state;
  
  const comment = normalizeComment(event.comment);
  
  // If it's a root comment while sorted by "newest", prepend
  // If sorted by "most liked", don't auto-insert — show "N new comments" banner
  if (!comment.parentId && sortMode === 'newest') {
    return insertComment(state, comment);
  }
  
  // For replies, insert into the parent's children
  if (comment.parentId && state.byId[comment.parentId]) {
    return insertReply(state, comment);
  }
  
  // Otherwise, buffer and show notification
  return { ...state, pendingCount: state.pendingCount + 1 };
}

// Reddit caps at depth 10, then shows "Continue this thread →"
const MAX_RENDER_DEPTH = 10;

function CommentThread({ commentId, depth }: { commentId: string; depth: number }) {
  const comment = useComment(commentId);
  const children = useChildren(commentId);
  
  if (depth >= MAX_RENDER_DEPTH && children.length > 0) {
    return (
      <div>
        <CommentNode comment={comment} depth={depth} />
        <Link to={`/comments/${commentId}`} className="text-primary text-sm ml-6">
          Continue this thread →
        </Link>
      </div>
    );
  }
  // ... normal recursive render
}

// Persist collapse state in sessionStorage so refreshes maintain context
function useCollapseState(postId: string) {
  const [collapsed, setCollapsed] = useState<Set<string>>(() => {
    const saved = sessionStorage.getItem(`collapsed-${postId}`);
    return saved ? new Set(JSON.parse(saved)) : new Set();
  });
  
  const toggle = useCallback((commentId: string) => {
    setCollapsed(prev => {
      const next = new Set(prev);
      next.has(commentId) ? next.delete(commentId) : next.add(commentId);
      sessionStorage.setItem(`collapsed-${postId}`, JSON.stringify([...next]));
      return next;
    });
  }, [postId]);
  
  return { collapsed, toggle };
}

// URL: /post/123#comment-456
// Need to load the comment + its ancestor chain for context
async function loadCommentWithContext(commentId: string): Promise<Comment[]> {
  // Server endpoint returns the comment + all ancestors up to root
  const { data } = await api.get(`/comments/${commentId}/context`);
  // Returns: [root, ..., parent, target_comment]
  
  // Auto-expand all ancestors and scroll to target
  for (const comment of data) {
    expandThread(comment.id);
  }
  
  // After render, scroll to the target comment
  requestAnimationFrame(() => {
    document.getElementById(`comment-${commentId}`)?.scrollIntoView({
      behavior: 'smooth',
      block: 'center'
    });
  });
  
  return data;
}

// Using the flattened list with react-window
import { VariableSizeList } from 'react-window';

function VirtualizedComments({ flatComments }: { flatComments: FlatComment[] }) {
  const listRef = useRef<VariableSizeList>(null);
  const heights = useRef<Map<string, number>>(new Map());
  
  const getItemSize = (index: number) => {
    return heights.current.get(flatComments[index].id) || 120; // Estimated height
  };
  
  const setItemSize = (id: string, height: number) => {
    heights.current.set(id, height);
    listRef.current?.resetAfterIndex(
      flatComments.findIndex(c => c.id === id)
    );
  };
  
  return (
    <VariableSizeList
      ref={listRef}
      height={window.innerHeight - 200}
      itemCount={flatComments.length}
      itemSize={getItemSize}
      overscanCount={5}
    >
      {({ index, style }) => (
        <div style={style}>
          <MeasuredComment
            comment={flatComments[index]}
            onMeasure={setItemSize}
          />
        </div>
      )}
    </VariableSizeList>
  );
}

import DOMPurify from 'dompurify';
import { marked } from 'marked';

function CommentContent({ content }: { content: string }) {
  const html = useMemo(() => {
    const raw = marked.parse(content, { breaks: true });
    return DOMPurify.sanitize(raw, {
      ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'code', 'pre', 'a', 'ul', 'ol', 'li', 'blockquote'],
      ALLOWED_ATTR: ['href', 'rel', 'target'],
    });
  }, [content]);
  
  return (
    <div
      className="prose prose-sm max-w-none"
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}