ReadThat 2: The SDUI Feed

Part 2 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.

Why SDUI

Reddit’s feed team described the motivation in Evolving Reddit’s Feed Architecture and the follow-up Rewriting Home Feed on Android & iOS: instead of one fat polymorphic Post object the client must interpret, the server sends the description of the exact UI elements the client will render, and controls their type and order.

What that buys:

• Reduced TTI. Feed payloads carry only render cells, no detail-only fields. ReadThat’s feed page budget is 64 KiB decoded at p50. Smaller payloads decode faster and hit the first content frame sooner.
• Out-of-band updates. A new feed unit (a new promotion format, a carousel variant) ships when the server ships it, not after three app-store review queues and a rollout curve.
• Client simplicity. The client’s job is to render, not to decide. Ranking, experimentation, and unit composition live in one place, server-side.

The wire model

A feed page is a list of groups; each group is an ordered array of cells, the atomic renderable pieces:

1
@Serializable
2
data class WireFeedPage(
3
    val groups: List<WireGroup>,
4
    /** Opaque cursor for the next page. Null means end-of-feed. */
5
    val nextCursor: String?,
6
)
7

8
@Serializable
9
data class WireGroup(
10
    val groupId: String,
11
    val cells: List<WireCell>,
12
)
13

14
@Serializable
15
sealed interface WireCell {
16
    val cellId: String
17

18
    @Serializable @SerialName("metadata")
19
    data class Metadata(...) : WireCell
20

21
    @Serializable @SerialName("title")
22
    data class Title(...) : WireCell
23

24
    @Serializable @SerialName("video")
25
    data class Video(...) : WireCell
26

27
    /** A cell type this client build does not understand. */
28
    @Serializable @SerialName("unknown")
29
    data class Unknown(
30
        override val cellId: String,
31
        val typeName: String,
32
    ) : WireCell
33
}

Wire.kt#L20-L216

Unknown is the load-bearing member. It’s what a current client produces when a newer server sends a cell type this build has never heard of. Keeping it in the type system, rather than throwing during parse, is what makes the feed forward-compatible. Its typeName feeds telemetry, so the platform team can measure how much of the feed each app version fails to render: the signal that says when it’s safe to drop an old build.

Flattening

The server sends two levels. A LazyColumn wants one:

1
SERVER (wire model)                     CLIENT (render list)
2

3
[ Group("post_1", [                     [ Metadata  key="post_1/meta"
4
      Metadata, Title, Image,             Title     key="post_1/title"
5
      ActionBar ]),                       Image     key="post_1/img"
6
  Group("post_2", [...]) ]                ActionBar key="post_1/actions"
7
                                          Divider   key="post_1/divider"
8
                                          ... ]

1
object FeedFlattener {
2
    fun flatten(
3
        groups: List<WireGroup>,
4
        registry: CellConverterRegistry = CellConverterRegistry(),
5
        appendDividers: Boolean = true,
6
    ): RenderList {
7
        val items = ArrayList<CellUi>(groups.sumOf { it.cells.size } + groups.size)
8
        val dropped = LinkedHashMap<String, Int>()
9

10
        for (group in groups) {
11
            var renderedInGroup = 0
12
            for (cell in group.cells) {
13
                val key = keyFor(group.groupId, cell.cellId)
14
                val ui = registry.convert(cell, key)
15
                if (ui != null) { items += ui; renderedInGroup++ }
16
                else { /* count dropped types for telemetry */ }
17
            }
18
            // A group that rendered nothing must not leave a stray divider —
19
            // otherwise a client that can't parse a new post type shows a feed
20
            // of empty separators instead of degrading invisibly.
21
            if (appendDividers && renderedInGroup > 0) {
22
                items += CellUi.GroupDivider(key = keyFor(group.groupId, "divider"))
23
            }
24
        }
25
        return RenderList(items = items, droppedCellTypes = dropped)
26
    }
27
}

FeedFlattener.kt#L26-L68

Two details carry the weight:

• Composite stable keys. LazyColumn uses keys for scroll restoration and recomposition scoping. The same cellId can legitimately appear in two groups (a shared promoted cell), so the key is groupId/cellId.
• Pure function. List<WireGroup> -> RenderList. No Android, no IO: trivially testable, trivially movable off the main thread.

The wire model above, running: every post in this capture is a group of server-described cells flattened into one LazyColumn.

The cons, honestly

SDUI is not free, and ReadThat runs into each cost:

• You lose type safety at the wire. The sealed WireCell hierarchy restores it per version, but the compiler can’t know what next month’s server sends: hence Unknown, the converter registry, and dropped-cell telemetry as a permanent tax.
• Interactivity is harder. A vote button described by the server still needs client behavior: optimistic state, outboxes, animation. ReadThat solves it by overlaying viewer state (item_state) onto the cached payload at merge time instead of rewriting server blobs; the ActionBar cell documents this seam directly (Wire.kt#L179-L194). Interaction-heavy screens fight the model constantly.
• Caching is more complicated. You’re caching presentation, not entities. ReadThat stores groups as server blobs in feed_groups keyed by (accountId, feedId, sortIndex), with a unique index enforcing ordering, and keeps mutable viewer state in a separate joined table so an optimistic like doesn’t invalidate a cached page.

Where SDUI stops

The most useful design decision in the repo is a boundary: :feature:comments is deliberately not SDUI. The feed’s shape varies (new unit types ship constantly) while its interactions are shallow; post detail’s shape is stable while its interactions are deep: vote, reply, collapse, expand. Reddit runs the same split. Knowing where SDUI stops is worth more than applying it everywhere. That screen gets its own page.

The backend half (signed keyset cursors, rank snapshots, how a feed page is assembled in D1) is in part 6.

← Part 1: Client architecture · Next: Part 3: The media feed →