ReadThat 1: Client Architecture

Part 1 of the ReadThat case study.

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

The client has one governing rule: render durable local state, then reconcile it with the network. Every other decision, the module graph, the cache tiers, the workers, exists to serve that rule.

Module graph

Android and iOS now have one product implementation: :feature:app-ui coordinates the KMP screen modules on both platforms, and :core:client owns the shared ViewModel, controllers, and offline-first repositories. The former Android-only UI/features and their rollback flag have been deleted; :app remains only where Android genuinely needs an APK/process host.

1
:app  (Android APK, WorkManager, process lifecycle)
2
 └── :composeApp  (Android entrypoint, process graph, saved-state adapter)
3

4
:iosApp (SwiftUI lifecycle + narrow Apple shims)
5
 └── :composeApp  (exported iOS framework + process graph)
6

7
:composeApp
8
 └── :feature:app-ui  (KMP application coordinator + navigation)
9
      ├── :feature:feed-ui / detail-ui / mediafeed-ui / search-ui /
10
      │   profile-ui / creation-ui / settings-ui / community-ui /
11
      │   auth-ui / ad-ui / shell-ui  (KMP screens)
12
      ├── :core:design / :core:image-ui / :core:media-ui  (shared UI + optimized target actuals)
13
      ├── :core:media-acquisition(+-ui) / :core:sharing(+-ui)  (shared policy; platform actuals)
14
      ├── :core:navigation  (shared destinations, bounded/versioned restoration)
15
      └── :core:client  (shared MVVM controllers + offline-first repositories)
16
           ├── :core:data  (Room 3 KMP schema/DAOs, commonMain)
17
           ├── :core:network  (shared contract; HttpEngine/OkHttp + URLSession actuals)
18
           ├── :core:model / :core:deeplink
19
           └── :core:observability  (KMP event contract)
20

21
Native capability modules keep platform engines behind shared contracts:
22
  :core:media / :core:media-ui / :core:image-ui
23
  :core:media-acquisition(+-ui) / :core:sharing(+-ui)

settings.gradle.kts · docs/ARCHITECTURE.md

The allowed dependency direction is enforced, not aspirational:

1
UI -> domain <- data -> network/platform
2
app -> feature -> core

Domain code does not depend on Compose, Room, HTTP, or platform classes. UI never calls a network client or a DAO. Cross-feature navigation passes identifiers, never mutable objects: :feature:feed-ui and :feature:detail-ui stay independent while feed dwell-prefetch and detail share one retained repository through the application composition root.

MVVM and unidirectional data flow

Each screen has one observable state and explicit intents:

1
Compose event -> ViewModel intent -> repository command
2
                                      |
3
                                      v
4
network response -> Room transaction -> Flow/StateFlow -> ViewModel state -> Compose

Room is the authoritative stream. A successful network response is committed before it becomes visible. Optimistic actions (votes, posts, community creation) write visible local state and an outbox row in one transaction; a worker reconciles later.

Paging 3 removes the usual hand-written page list, cursor, and isAppending state. SharedFeedController owns the lifecycle-independent feed behavior; the shared ReadThatViewModel retains its Room-backed pages for both Android and iOS:

1
/**
2
 * Lifecycle-independent feed controller shared by focused feature ViewModels
3
 * and the application ViewModel. Navigation and native rendering stay at the
4
 * host edge; Room Paging, refresh classification, mutations, comment prefetch
5
 * and media handoff have one implementation.
6
 */
7
internal class SharedFeedController(
8
    private val repository: OfflineFirstRepository,
9
    ...
10
) {
11
    val cards: Flow<PagingData<FeedCard>> = repository.pagedFeedFor(...)
12

13
    fun toggleLike(itemId: String) = vote(itemId, 1)
14
    fun vote(itemId: String, value: Int) {
15
        if (itemId.isBlank() || value !in -1..1) return
16
        scope.launch { repository.votePost(itemId, value, performanceSurface) }
17
    }
18
}
19

20
class ReadThatViewModel(...) : ViewModel() {
21
    private val cachedPagedFeed = feedController.cards.cachedIn(viewModelScope)
22
    val pagedFeedCells = cachedPagedFeed.map { paging ->
23
        paging.flatMap { card -> card.cells }
24
    }
25
}

SharedFeedController.kt · ReadThatViewModel.kt#L212-L221

Offline-first, by construction

The network↔database seam is a Paging 3 RemoteMediator. It never serves pages to the UI; Room’s PagingSource does. The mediator only runs when the DB runs out of cached pages:

1
/**
2
 * - Offline works by construction. With no network, APPEND fails and
3
 *   Paging keeps serving whatever the DB already holds.
4
 * - Paging survives process death, because the cursor is a row.
5
 * - One writer. Both the mediator and an optimistic like write to Room;
6
 *   Room invalidates the PagingSource and the UI re-emits.
7
 */
8
private inner class SharedFeedRemoteMediator(
9
    private val account: String,
10
    private val feedId: String,
11
    private val subreddit: String?,
12
    ...
13
) : RemoteMediator<Int, GroupWithState>()

OfflineFirstRepository.kt#L461-L572

Startup follows the same rule. MainActivity renders a cached shell immediately and reports fully drawn at that boundary; no network request is on the first-frame path. Measured on a Pixel 10 Pro with a warm process: p50 = 11 ms across ten am start -W samples. A cold process was 575 ms.

The two-tier cache contract

Every user-visible data family has a bounded hot tier and a durable tier, and every structured key includes the account identity. A condensed view (the full contract covers the remaining families):

The data layer page covers sizing and eviction; the point here is the contract: L1 never independently decides correctness. It removes query and mapping work from the hot render path. Room decides what exists.

Background workers

On Android, deferred work runs through WorkManager; the mutation lanes are network-constrained and idempotent through client-minted mutation IDs. iOS calls the same shared maintenance/repository operations from a BGTaskScheduler host.

• FeedRefreshWorker: one unique periodic worker; refreshes Room first, warms a bounded image/poster plan on a validated path, then (only on unmetered, non-Data-Saver networks with autoplay enabled) asks Media3’s PreCacheHelper to persist the first two seconds of at most one ready video.
• Vote / post / community outbox workers: unique one-time workers that drain durable outboxes. A post targeting a locally pending community waits at an explicit ordering barrier; when the community reconciles, dependent posts re-enqueue immediately instead of sitting in backoff.
• Telemetry drain: up to 50 events per request, immediate when connected, 15-minute safety sweep.

FeedWorkers.kt · PostUploadWorker.kt · SubredditCreationWorker.kt

Concurrency is handled where it actually bites: Paging and WorkManager create independent sync objects, so feed serialization uses a process-wide account/feed mutex, and an append re-reads its cursor after acquiring it, so a cursor captured before a competing refresh can never append an older generation.

Jetpack inventory

The KMP boundary is deliberate: contracts, UI, ViewModels/controllers, Room schema/DAOs, repositories, and paging policy are shared. Platform code supplies the optimized engines and lifecycle hooks—Media3 vs AVPlayer, HttpEngine/OkHttp vs URLSession, WorkManager vs Apple background scheduling, secure storage, pickers, and system share sheets. Observability details live in part 7.

📷 Screenshot placeholder: module graph rendered, plus the app shell on first frame.

Next: Part 2: The SDUI feed →