The Android App Template

Three layers, each owning one thing:

• UI (Composable + ViewModel) - renders the current state and emits user intents.
• Domain (use cases) - the business rules: what a "like" means, what counts as a valid comment, which query shape a given view needs.
• Data (repository) - the cache and the network. The single component that touches both Room and OkHttp; to the domain layer above it is just a Flow source.

Unidirectional Data Flow (UDF) is the rule the three layers enforce: no layer reaches across or mutates another layer's state.

Why this matters in practice

A bug like "the like count is wrong" has a small search space - it must be either an emit-from-below or a render-from-above. Without UDF, the same bug could be in any of N code paths that write the shared state, and the only way to find it is to read all of them.

How state actually moves up: cold Flow, hot StateFlow

The data layer hands you a cold Flow that only runs while something is watching - collecting dao.observeAll() opens a Room query that re-emits whenever the table changes, and each collector re-runs the producer. The ViewModel turns that into a hot StateFlow<UiState> that always has a value ready for the screen, so Compose gets a value now and a rotation doesn't restart the query. The rest of the Flow mechanics live in State Management and Concurrency.

The use-case design rule

The rule that interviewers probe: reads multiply by view, writes converge through one entrypoint.

• Reads: every new way to view data (filter by author, search, sort, archived-only) needs its own use case, because each runs a different query. You can't reuse one.
• Writes: a new action (like, unlike, comment, bookmark) does not need a new use case. The plumbing is identical for all of them - open a transaction, apply the change, queue an outbox row, kick the dispatcher. Only the action kind changes, so it's just a new enum value plus one branch in the switch.

The smell it warns against: LikeItemUseCase, UnlikeItemUseCase, CommentUseCase as separate classes - N copies of the same plumbing, varying only in the kind string they pass down. Explodes the domain layer for nothing.

The exception: if an action needs real pre-write logic (validate a comment, rate-limit, route to a different repository), put that in a domain helper the one use case calls - don't spin up a parallel use case class for it.

Hilt turns the layer boundaries into build errors - modules sit at the two seams, and the domain and data layers should still compile with every Hilt import stripped. The mechanics are covered in Dependency Injection.

Keep a fast in-memory copy (L1) in front of the on-disk Room cache (L2, Android's SQLite layer) so scrolling never waits on a database query, and let the repository hide the network behind one Flow.

The diagram below is the read-path delta - the four lanes the read touches. UI and Domain are pass-through (the screen subscribes via ObserveItems) and omitted. L1 is a hot mirror of L2, kept hydrated by Room's Flow observer, reads return L1 directly with no SQLite round-trip:

class ItemRepositoryImpl @Inject constructor(/* dao, remote, scope */) : ItemRepository {
    private val l1 = MutableStateFlow<List<Item>>(emptyList())
 
    init {
        // L1 is a hot mirror of L2, Room's Flow drives it.
        dao.observeAll().onEach { l1.value = it.toDomain() }.launchIn(scope)
    }
 
    override fun observeItems(): Flow<List<Item>> = l1
 
    override suspend fun refresh() {
        val page = remote.fetchItems(cursor = null)             // network
        dao.replaceHead(page.items.toEntities())                // L2 write, L1 hydrates via observer
    }
}

Update the screen instantly, write the action into a durable queue (the "outbox"), and let a background worker push it to the server - so a tap survives offline, a flaky network, and the OS killing the app.

The outbox pattern is borrowed from email clients - Gmail and Outlook have shipped it for a decade because a dropped like and a dropped email have the same failure mode: silent loss. The difference is email users notice, feed users don't, so the bar for apps is lower and most teams clear it by accident.

The diagram below is the write-path delta - the four lanes the write touches. UI and Domain are pass-through (the tap arrives via PerformAction) and omitted. The outbox lives in the same Room database as the item cache, so a queued write survives process death exactly the way cached items do:

suspend fun perform(itemId: String, kind: ActionKind, payload: String? = null) {
    val actionId = UUID.randomUUID().toString()
    db.withTransaction {
        applyOptimisticUpdate(itemId, kind, payload)            // when(kind) → LIKE +1, COMMENT push, ...
        outboxDao.insert(OutboxAction(actionId, itemId, kind, payload))
    }
    outboxDispatcher.kick()                                      // best-effort wake
}
 
private suspend fun applyOptimisticUpdate(itemId: String, kind: ActionKind, payload: String?) {
    when (kind) {
        LIKE    -> dao.toggleLike(itemId, liked = true)
        UNLIKE  -> dao.toggleLike(itemId, liked = false)
        COMMENT -> dao.insertLocalComment(itemId, body = payload!!)
        // new kinds add a branch here, not a new use case.
    }
}

Three layers each own one kind of error: OkHttp retries the transient ones, the repository maps HTTP codes to domain failures, and the UI shows an offline banner for session-wide outages.

Retrying transient failures

Retries belong at the network layer, not in app code. An OkHttp Interceptor (a hook that sits in the middle of every request and response, like middleware - see HTTP Client Library) examines the response and the request method, on a 5xx or a SocketTimeoutException, it retries up to N times with min(maxBackoff, base * 2^attempt) + uniform(0, base) between attempts. The jitter is what prevents the install base from synchronising retries against a recovering server. Idempotent methods (GET, HEAD, PUT, DELETE, plus POST carrying an Idempotency-Key the way the outbox does) retry, non-idempotent POST and PATCH don't - retrying them risks duplicate effects on the server.

class RetryInterceptor(private val maxAttempts: Int = 3) : Interceptor {
    override fun intercept(chain: Chain): Response {
        var attempt = 0
        while (true) {
            val res = runCatching { chain.proceed(chain.request()) }
            if (res.isSuccess && !res.getOrNull()!!.shouldRetry()) return res.getOrNull()!!
            if (++attempt >= maxAttempts || !chain.request().isRetryable()) return res.getOrThrow()
            Thread.sleep(backoff(attempt) + Random.nextLong(0, JITTER_MS))  // jittered backoff
        }
    }
}

See the HTTP Client Library design for the deeper retry-semantics treatment - Retry-After handling, method-aware idempotency, and the connection-pool behavior under failure.

Repository maps HTTP errors to domain failures

4xx errors are not retryable - the request was wrong. The repository wraps the Retrofit call in a runCatching { ... } and translates HttpException(400..499) into a sealed DomainError type (NotFound, Forbidden, BadInput, ...). The UI matches on the sealed type, not on raw HTTP codes.

Retrying a 4xx is always a bug, even though it looks harmless. The server told you "no" - bad input, forbidden, not found. Retrying burns battery on a response that won't change. The retry budget is for transient failures, and 4xx is the definition of permanent.

UI banner state for network outages

Wifi loss is not an error per request - it's a session state. A NetworkObserver (built on ConnectivityManager.registerDefaultNetworkCallback) emits a Boolean Flow that the UI overlays as a "No connection" banner whenever it's false. Errors on individual requests inside an offline session don't show as toasts - the banner is the right signal because it explains why everything is failing at once.

Never paginate by position (offset or timestamp), pass back an opaque cursor the server hands you, and let Paging 3 drive Room as the source of truth.

Offset pagination is the #1 thing I reject in design review. Ship the cursor on day one, it's the same code.

Split the app into per-feature modules on day one, the cost is a few hours of Gradle now, and it saves a multi-quarter migration nobody wants to own at year two.

I've had apps where the single-module build hit 15 minutes. Every UI tweak rebuilt the data layer, every data change rebuilt every feature, and the team's feedback loop died. Making a module split today is easier than ever - point your AI agent at it and let it work on splitting. It's not really system design content, but it's real life pain that's very easily solvable regardless, and interviewers are looking at the practicality of your thinking.

The right shape is straightforward and the patterns are well-established at Airbnb, Netflix, Square, and Google's own consumer apps.

Per-feature modules

Each feature is a pair of Gradle modules: :feature:foo (UI + ViewModels) and :feature:foo-data (domain + data + DI). The UI module depends on its data module's domain interfaces only - the implementations are wired via Hilt. A feature module never depends on another feature module, cross-feature calls go through an API module (:feature:foo-api) that declares the interface and is depended on by both.

Shared library modules

Cross-cutting infrastructure lives in :lib: modules: :lib:network (OkHttp + Retrofit setup), :lib:database (Room base configuration), :lib:designsystem (theme, common Compose components), :lib:common (utilities). Features depend on libs, libs never depend on features.

A representative module structure

:app                                ← assembles everything, no logic
:feature:feed                       ← UI + ViewModels
:feature:feed-data                  ← domain + data + Hilt wiring
:feature:feed-api                   ← public interface for cross-feature calls
:feature:detail                     ← UI + ViewModels
:feature:detail-data
:feature:detail-api
:lib:network                        ← OkHttp + Retrofit base
:lib:database                       ← Room base + migrations
:lib:designsystem                   ← Compose theme + components
:lib:common                         ← utilities, extensions

Three practical benefits follow from the split. (1) Build time - touching :feature:feed UI doesn't rebuild :feature:detail. That isolation also bounds failure: (2) a bug in one feature's data layer can't reach into another's. And the team scales with the module count: (3) three engineers can work on three features without merge conflicts in shared files.

Big images eat memory and decode time, and the library will not save you: set the display size before loading and decode smaller-than-original. (ARGB_8888 is 4 bytes per pixel, the default - see Memory and GC.)

Coil is the Compose-era default (coroutine-based, AsyncImage-native, shares OkHttp with the API client). The rest of this deep dive is what you do with it - none of which Coil does for you by default.

1. Placeholder dimensions, not placeholder drawables

The bug everyone hits first: an AsyncImage with no size hint renders at 0×0 until the bytes decode, then the layout reflows and everything below it jumps. Users read this as "the app is broken". The fix is to give Compose the dimensions before the bytes arrive - either from width/height metadata the server sends with each Item, or from a fixed aspect ratio the feature commits to.

AsyncImage(
    model = item.imageUrl,
    contentDescription = null,
    modifier = Modifier
        .fillMaxWidth()
        .aspectRatio(item.imageAspectRatio),    // 16:9, 1:1, whatever the API returned
    contentScale = ContentScale.Crop,
)

The aspectRatio modifier reserves the layout slot before the image loads. No reflow on decode, the placeholder is a colored rectangle of the correct size. This single modifier is the difference between a list that scrolls cleanly and one that bounces.

2. Downsampled decode

Coil auto-downsamples to the target Size the request is rendered at - but only if the target size is known at request time. Sizing the AsyncImage with aspectRatio (above) gives Coil the target dimensions automatically, off-screen requests need explicit .size(...).

ImageRequest.Builder(context)
    .data(url)
    .size(Size(400, 225))                       // explicit target size
    .scale(Scale.FILL)                           // crop rather than letterbox
    .allowHardware(true)                         // Bitmap.Config.HARDWARE: available API 26+, safe to default from 28
    .build()

Why the target size matters - a 4000x3000 JPEG decoded at native resolution is 48 MB at ARGB_8888, decoded for a 400-px column it's a few hundred KB - is the two-pass-decode / inSampleSize / Bitmap.Config.HARDWARE story, and it's covered in Image Loading Internals. The design move here is giving Coil the dimensions so it picks the right sample size; the platform substrate that makes the sample size the right lever lives on that page.

3. Two-tier cache, parallel to the item cache

Coil's caches mirror the item-data ladder - same shape, separate budgets. The memory cache holds decoded Bitmaps, the disk cache holds the compressed bytes off the wire; the full ladder (cache key shape, hit-miss path through decode and network) is covered in Image Loading Internals. What this design pins is the budgets:

• L1 memory cache - Coil defaults to ~20% of available heap (15% on low-RAM devices), this design pins it to Runtime.maxMemory() / 8 to match the item L1 budget.
• L2 disk cache - Coil defaults to 2% of free disk space (clamped to 10-250 MB) in cacheDir, for image-heavy apps pin it to 200 MB.

val imageLoader = ImageLoader.Builder(context)
    .memoryCache { MemoryCache.Builder(context).maxSizePercent(0.125).build() }  // 12.5% heap
    .diskCache { DiskCache.Builder().maxSizeBytes(200L * 1024 * 1024).build() }  // 200 MB
    .okHttpClient(appOkHttpClient)  // share the API client's connection pool + TLS
    .build()

Sharing appOkHttpClient is the under-noticed move: connection reuse to the image CDN, the same retry/auth interceptors, and a single TLS session pool. Two separate OkHttp instances pay the handshake cost twice. The disk cache also drives OkHttp's If-None-Match / If-Modified-Since so a server 304 Not Modified returns cached bytes without re-downloading.

4. Memory pressure handling

On onTrimMemory(...) Android signals the app to release caches before the OOM killer steps in. Coil registers a callback that trims the memory cache under pressure (halving it at TRIM_MEMORY_RUNNING_LOW) and clears it entirely once the app is backgrounded, the disk cache is unaffected (off-heap). The next visible image loads from disk - one-frame stutter, no crash. On a low-end device this is what keeps the app on screen when the user multitasks into a heavy game and back.

FCM (Firebase Cloud Messaging - Google's push service, the one persistent socket Play Services maintains for every app on the device) is the wake-up channel, the REST API is still the source of truth. The receiver enqueues a WorkManager job and returns immediately, the worker calls repository.refresh() - the same entrypoint a cold-start read uses - so the network call stays inside the repository and the cache update stays single-owner.

The diagram below is the push-path delta - only the three lanes the push touches. UI, Domain, and Local Storage are unchanged from the Phase 3 architecture and omitted. The refresh flows left through RemoteDataSource → REST API (the cold-start path), FCM enters from the right:

Why data-only and not notification: the notification payload auto-displays on Play Services' terms, with no chance for the app to suppress based on local state or update an existing notification. Production apps send data-only so onMessageReceived runs every time and the app's code decides what to surface, the full tradeoff is in Push and Notifications.

Two transport knobs cross both payload kinds. priority - high wakes the device immediately and bypasses Doze, normal batches with the next maintenance window, and abusing high gets the app deprioritized. collapse_key - several messages with the same key queued while offline collapse to the latest on reconnect, right for "items changed", wrong for chat.

In code, the pattern is two short classes - the receiver does nothing but enqueue, the worker does nothing but call ItemRepository.refresh():

@AndroidEntryPoint
class PushReceiver : FirebaseMessagingService() {
    @Inject lateinit var workManager: WorkManager
    override fun onMessageReceived(msg: RemoteMessage) {
        // Push payload is a *trigger* ("something changed"), not data.
        workManager.enqueue(OneTimeWorkRequestBuilder<ItemsRefreshWorker>().build())
    }
}
 
@HiltWorker
class ItemsRefreshWorker @AssistedInject constructor(
    @Assisted ctx: Context, @Assisted params: WorkerParameters,
    private val itemRepository: ItemRepository,
) : CoroutineWorker(ctx, params) {
    override suspend fun doWork() =
        runCatching { itemRepository.refresh() }
            .fold(onSuccess = { Result.success() }, onFailure = { Result.retry() })
}

Why the receiver enqueues instead of doing the work directly. onMessageReceived runs on a binder thread with a ~10-second budget before ANR, calling repository.refresh() there risks blowing it on a slow network. Enqueueing defers to a durable worker that survives both the binder timeout and process death.

The worker carries NetworkType.CONNECTED. A push that lands while offline enqueues a worker that won't run until connectivity returns. WorkManager persists the request, so the deferred refresh survives reboot.

The self-healing property. The client reconciles the full head page on every cold start anyway, so a missed or coalesced push is caught by the next launch. Push is a latency optimization, not a correctness mechanism - and FCM delivery is not guaranteed under Doze or battery-saver modes, so it can't be.

WorkManager is the durability primitive on both the push path and the write path - it persists pending work to its own SQLite DB and resurrects it after process death. The write-path counterpart that drains the outbox queue is unpacked in dd3.