ReadThat 4: Post Detail & Comments

Part 4 of the ReadThat case study.

📲 Try it live: Download the ReadThat APK (8.8 MB, Android 8+). Open the file on your phone and allow “install unknown apps” if prompted.

TL;DR: why comments are hard

Comment thread is an arbitrarily deep, arbitrarily wide tree and can hold more nodes than a phone should download. Also they are mixed with media, mutated constantly (votes, replies, collapses), and rendered by a UI toolkit that wants a flat list. This makes comments an interesting data structure, client/server boundary decision, UI implementation and cacheing problem. Every decision below is about choosing which part of the tree to materialize, where, and when, and doing it without ever visibly reordering what the user is reading.

Left: feed to post detail, with the prefetched first phase rendering instantly. Right: a 20-level-deep fixture thread: depth rails, collapse badges, and the continue-thread handoff at the depth cap.

The problem, precisely

1. Depth is unbounded in the data but not in the UX: indentation past ~10 levels is unreadable on a phone, and recursive algorithms on real threads are a StackOverflowError.
2. Size is unbounded: a viral post has 50k comments. You need a principled answer to “which N do we send first?”
3. What’s worth rendering is a ranking problem: the best reply to the third comment may matter more than the ninth root comment.
4. Loading is incremental: every truncation point needs a cursor, and expanding one must splice into the middle of an existing tree without disturbing it.
5. State overlays structure: votes, collapses, and in-flight replies are per-viewer state on top of shared structure.

Data structures and schema

Wire: a recursive tree of two node types, Comment (with children) and LoadMore (a cursor standing in for absent children, carrying at most 100 child IDs). CommentWire.kt

Storage: normalized, never a recursive blob: Room tables comment_threads, comment_nodes, post_headers, all account/post-scoped. Encoding uses iterative preorder traversal; decoding is iterative bottom-up, so a deep thread cannot consume the call stack.

Render: a flat List<CommentRow> where each row carries renderDepth:

1
sealed interface CommentRow {
2
    val key: String
3
    /** Depth on THIS SCREEN — always relative to this screen's root. Distinct
4
     *  from structural depth, which is the server's business and never
5
     *  crosses the wire. */
6
    val renderDepth: Int
7

8
    data class Comment(..., val isCollapsed: Boolean,
9
                       val collapsedDescendants: Int) : CommentRow
10
    data class LoadMore(..., val parentId: String?) : CommentRow
11
    /** Depth-cap affordance: NAVIGATES to a re-rooted screen (permalink
12
     *  behavior). Different intent, different row type, different metric. */
13
    data class ContinueThread(..., val parentId: String?) : CommentRow
14
}

CommentFlattener.kt#L9-L51

Server vs client processing

The central tradeoff: who builds the tree?

Reddit’s published algorithm, implemented literally in the Worker: push roots into a max-heap by score, repeatedly pop the best comment anywhere in the tree, attach it, push its children as candidates; whatever remains groups by parent into load_more cursors:

1
const heap = new MaxHeap();
2
for (const root of byParent.get(rootCommentId) ?? []) heap.push({ row: root, depth: 0 });
3
const selected = new Map<...>();
4

5
while (heap.size > 0 && selected.size < maxCount) {
6
  const candidate = heap.pop();
7
  ...
8
  if (candidate.depth + 1 <= maxDepth) {
9
    for (const child of children) heap.push({ row: child, depth: candidate.depth + 1 });
10
  }
11
}

comments.ts#L227-L247

Because the heap is score-ordered globally, a count=200 tree expands children under comments that were childless leaves at count=8. There’s a test asserting this happens; it’s the premise of the flicker bug below. Depth caps at 10 (Reddit’s number) and every cursor carries ≤ 100 child IDs (comments.ts#L14).

Why fixed sizes (8, then 200)? Reddit pre-computes and caches trees at those exact parameters; clients that request the same sizes hit the cache. Ask for an off-menu size and you force a dynamic build. A JVM test pins the client to exactly (8, 10) then (200, 10).

Client implementation

Two-phase load. Request the 8-tree, render immediately; request the 200-tree, merge in behind the reader. Prefetch makes phase 1 free: the feed calls CommentsRepository.prefetch(postId) after dwell suggests intent, so tap-through renders without touching the network. Reddit’s published cost for the same feature: ~40k extra requests/second. Prefetching isn’t free, which is why dwell gates it.

The anti-flicker merge. Reddit’s published problem: the 200-tree suddenly auto-expands children and “leads to a jarring UX.” The client-side contract:

1
/**
2
 * Anything already on screen keeps its position and its expansion state.
3
 * The larger tree may only ADD. It may never auto-expand something the
4
 * small tree showed collapsed, and never reorder what the user is reading.
5
 */
6
fun merge(existing: CommentTree?, incoming: CommentTree, ...): MergeResult

Nodes that were childless on screen but gained children get auto-collapsed: and those IDs are kept in a separate set from user collapses: never persisted, never announced to TalkBack, because merger artifacts are not user intent. CommentTreeMerger.kt#L26-L86

Iterative flattening. Tree → flat rows with an explicit stack, honouring collapse (hides the whole subtree, reports collapsedDescendants for the “+12” badge), load-more cursors at the depth of the children they replace, and the depth-10 switch from expand-in-place to “continue this thread” navigation:

1
val stack = ArrayDeque<Pair<CommentNode, Int>>()
2
for (node in tree.roots.asReversed()) stack.addLast(node to 0)
3
while (stack.isNotEmpty()) {
4
    val (node, depth) = stack.removeLast()
5
    ...
6
}

CommentFlattener.kt#L83-L169: there’s a test flattening a 5,000-deep thread; recursion would blow the stack. Tree mutations (splice, vote, reply) are also iterative and path-copy, so untouched subtrees keep referential identity and Compose skips them.

Two-stage UiState. The flatten is expensive; loading flags churn constantly. So derivation happens in two combine stages: flag churn re-executes cheap assembly, never the flatten, and the flatten runs off the main thread (CommentsViewModel.kt#L105-L133). Detailed in part 10.

Why not Paging 3 here? A PagingSource models a flat ordered sequence; a comment continuation splices under any parent and must preserve collapse state and depth. Flattening server data first would throw away exactly the structure the feature mutates. The tree-aware equivalent: viewport visibility is a UDF intent, the ViewModel prefetches one cursor when it’s within six rows, one automatic branch in flight, errors never auto-retry.

Metrics: what to optimize for

Anchor metric: Comments TTI: tap in feed → first frame containing a real comment. Reddit’s baseline was ~2.3s iOS / ~2.6s Android; after the two-phase split, prefetch, and payload trims they reported p90 −60.9% / −59.4%, a −30% detail-load failure rate, and +4% comments viewed (Instant Comment Loading).

The hierarchy, from top-line to diagnostic:

ReadThat’s budgets: prefetched Comments TTI p90 ≤ 1,000 ms; initial-8 fetch p90 ≤ 500 ms; full-200 p90 ≤ 1,200 ms (docs/PERFORMANCE_OBSERVABILITY.md).

A/B testing strategy

The knobs are cheap to vary server-side because clients treat sizes as parameters:

1. First-phase size (8 vs 12 vs 16): goal on Comments TTI and early scroll depth; guard on payload size and cache hit rate.
2. Prefetch dwell threshold (aggressiveness): goal on prefetched-TTI share and comments viewed; guard on wasted-prefetch ratio and data use on metered networks. This is the experiment with a real infra cost (Reddit’s 40k rps): run it with a cost curve, not just a UX curve.
3. Depth cap / continue-thread threshold (10 vs 8 vs 12): goal on comments viewed per post and continue-thread click-through; guard on readability complaints and deep-thread interaction rates.
4. Ranking variant inside the heap (score vs recency-boosted): goal on comment votes cast and replies posted; guard on total comments viewed.

Assignment must be viewer-bucketed, not post-bucketed (posts have wildly different tree shapes), and every variant reports the same fixed metric boundaries: a number without its boundary defined is not the same metric. Because sizes are cache keys, each variant needs its own pre-computed cache population; that’s the hidden infra cost of experimenting here, and why variants should be few and long-lived.

What landed

Server-built best-first trees at fixed (8, 200) sizes, dwell-gated prefetch, anti-flicker client merge, normalized Room L2 + bounded LRU L1, iterative everything, two-stage state derivation, and tree-aware progressive loading, with each behavior pinned by a JVM test (12 test files). The full rationale lives in comments/README.md.

← Part 3: The media feed · Next: Part 5: The data layer →