DEV Community: Ouday khaled

Pure Reducers in Kotlin: Why Your Android Unit Tests Should Run in 5 Milliseconds

Ouday khaled — Tue, 21 Apr 2026 16:51:01 +0000

Reducer unit tests clear in about five milliseconds each, with no dispatcher setup, no MockK, no Turbine, and no ViewModel. That speed is not a micro-optimization — it reshapes the test pyramid, moves 80% of Android presentation tests to pure JUnit, and keeps the feedback loop under a second on a laptop. This article walks through the Kotlin contract that makes the five-millisecond figure possible, and the disciplines that keep it there.

What a reducer is

object FactsReducer : MviReducer<FactsState, FactsIntent> {

    override fun reduce(state: FactsState, intent: FactsIntent): Reduction<FactsState, FactsIntent> =
        when (intent) {
            // User gestures
            FactsIntent.Refresh             -> state.onRefresh()
            FactsIntent.LoadNextPage        -> state.onLoadNextPage()
            FactsIntent.DismissError        -> state.onDismissError()
            FactsIntent.FetchRandomFact     -> state                          // middleware only
            FactsIntent.Retry               -> state.onRetry()
            is FactsIntent.SearchChanged    -> state.onSearchChanged(intent.query)
            is FactsIntent.ToggleBookmark   -> state.onToggleBookmarkRequested(intent.factId)
            is FactsIntent.FactClicked      -> state                          // navigation → effect only
            // Internal
            is FactsIntent.SearchQueryCommitted -> state.onSearchCommitted(intent.query)
            is FactsIntent.FactsReceived        -> state.onFactsReceived(intent.facts, intent.append)
            is FactsIntent.FactsLoadFailed      -> state.onFactsLoadFailed(intent.cause)
            is FactsIntent.BookmarkStarted      -> state.onBookmarkStarted(intent.factId)
            is FactsIntent.BookmarkConfirmed    -> state.onBookmarkConfirmed(intent.factId)
            is FactsIntent.BookmarkFailed       -> state.onBookmarkFailed(intent.factId, intent.cause)
        }.wrap()

    private fun FactsState.onRefresh(): FactsState =
        if (isRefreshing || isLoading) this
        else copy(isRefreshing = true, error = null)

    // ... unchanged ...

    private fun FactsState.wrap(): Reduction<FactsState, FactsIntent> = Reduction(this)
}

The reducer is a top-level object implementing MviReducer<S, I>. It is a plain fun, never suspend, never inline, never generic, with no constructor parameters, no @Inject-ed collaborators, and no reference to the enclosing Store. Given a state and an intent, it returns a Reduction(newState, followUps) — one new state plus an optional list of follow-up intents the runtime dispatches next.

The when is exhaustive against a sealed FactsIntent interface. No else branch, by design. When a future branch adds FactsIntent.ExportCsv, the Kotlin compiler rejects the reducer until a matching case exists, so the contract stays total and silent-drop bugs are compile errors. Each branch is a one-line delegation to a named extension helper — state.onRefresh(), state.onLoadNextPage() — which keeps the when scannable at a glance and lets each helper be tested in isolation, one gesture at a time, under 300 lines per reducer.

Rule: reduce takes (State, Intent), returns Reduction, and depends on nothing else.

No-op detection

// Bad — always allocates, always recomposes.
private fun FactsState.onDismissError(): FactsState = copy(error = null)

// Good — same instance when already dismissed.
private fun FactsState.onDismissError(): FactsState =
    if (error == null) this else copy(error = null)

Every intent runs the reducer. Returning copy() unconditionally allocates a new state reference and triggers wave recompositions across every subscribed composable, even when no field changed. The fix is a reference check first, a copy second. Compose's structural-equality skip then short-circuits the recomposition, and the scrolling list stops stuttering at the end of the feed.

Apply the pattern to every branch, not to hot paths alone. The obvious offenders are SearchChanged(query), which fires per keystroke, and the bookmark loading pair BookmarkStarted / BookmarkConfirmed, which fires per tap. Less obvious is FactsReceived with an empty list during pagination — when the backend has no more pages, the branch must return the same state instance, not a fresh copy() with identical fields. Reducer tests lock the invariant with a single assertSame(state, out.state) call, which doubles as a grep-able marker that the branch is intentional rather than forgotten.

The pairing with Compose is what closes the loop. FactsScreen subscribes via collectAsStateWithLifecycle(), which uses structural equality to decide whether a new state warrants a recomposition. Returning the same reference from a no-op branch short-circuits that check before any @Composable in the tree reruns, and a correctly-stable FactCard(fact: CatFact, onClick: () -> Unit) skips too. The same discipline applies to ImmutableList and ImmutableSet: if a branch appends zero items, return the input list — persistentListOf() constructors and .toImmutableList() round-trips both allocate fresh instances that defeat skipping for the whole list column.

Rule: on a no-op intent, return the same state reference so Compose skips the recomposition.

Mutation composition

typealias Mutation<S> = (S) -> S

operator fun <S> Mutation<S>.plus(next: Mutation<S>): Mutation<S> =
    { s -> next(this(s)) }

// Compose for an intent that updates multiple concerns:
private fun FactsState.onFactsReceived(
    facts: ImmutableList<CatFact>, append: Boolean,
): FactsState {
    val updateFacts: Mutation<FactsState> = { s ->
        val merged = if (append) (s.facts + facts).distinctBy { it.id }.toImmutableList() else facts
        s.copy(facts = merged)
    }
    val clearLoading: Mutation<FactsState> = { it.copy(isLoading = false, isLoadingMore = false, isRefreshing = false) }
    val clearError: Mutation<FactsState> = { it.copy(error = null) }
    val advancePage: Mutation<FactsState> = { it.copy(currentPage = if (append) it.currentPage + 1 else 1) }
    return (updateFacts + clearLoading + clearError + advancePage)(this)
}

A Mutation<S> is a function from state to state — nothing more. The + operator composes two mutations left-to-right, and a branch that updates several concerns at once becomes a pipeline of named mutations applied to the input state. The codebase uses one name: Partial and PartialState are banned aliases, and introducing them fails review on sight.

Reach for mutations when several concerns co-update, when each concern deserves an independent unit test, or when the reducer approaches the 300-line ceiling and decomposition is the alternative to splitting the store into two. Avoid them for single-field updates — a named Mutation wrapping one copy is noise. The rule of thumb: three concerns in one branch, compose mutations; one concern, inline copy. Middleware-level orchestration stays out of scope entirely, and a follow-up Intent in the Reduction is the only way the reducer asks the runtime for anything beyond the new state.

Rule: compose Mutations when a branch updates independent concerns; inline copy when it updates one field.

Why tests are 5ms

Tier	Tests per feature	Runtime (wall clock)
Reducer	30–50	under 1 s total
Middleware	10–20	under 3 s total
Store integration	5–10	about 5 s total
Screen	5–10	device-bound
Macrobenchmark	2–4	physical device, slow

class FactsReducerTest {

    @Test
    fun `Refresh on idle sets isRefreshing and clears error`() {
        val out = FactsReducer.reduce(
            state = FactsState(error = UiText.Raw("stale")),
            intent = FactsIntent.Refresh,
        )
        assertTrue(out.state.isRefreshing)
        assertNull(out.state.error)
        assertTrue(out.followUps.isEmpty())
    }

    @Test
    fun `Refresh while already refreshing returns same instance`() {
        val state = FactsState(isRefreshing = true)
        val out = FactsReducer.reduce(state, FactsIntent.Refresh)
        assertSame(state, out.state)
    }

    // ... unchanged ...
}

The reducer is pure data in, pure data out. Tests call FactsReducer.reduce(state, intent) directly, assert on the returned state and followUps, and exit. There is no @Before, no Dispatchers.setMain, no runTest, no MockK, no fake repository, no Turbine, no Compose rule. A well-populated reducer tier carries 30–50 tests per feature — happy path, no-op branch, error mapping, follow-up list — and the full file clears in under a second.

Contrast with the middleware tier, where every test spins up a StandardTestDispatcher, a fake repository, a dispatch capture list, and ends with advanceUntilIdle. Useful and necessary, but an order of magnitude slower per test. The store-integration tier piles on real middlewares, Turbine, and SavedStateHandle wiring; the screen tier adds a Compose rule; macrobenchmark adds a physical device. That asymmetry is what lets the reducer tier stay the default and every tier above it the exception. The numbers in the diagram are typical orders of magnitude on a warm JVM, not benchmark-grade measurements; the relative shape is the point, and it holds across every feature in the playbook.

Rule: if a reducer test needs a dispatcher or a fake, it belongs to the middleware tier.

What belongs outside the reducer

Violation	Fix
Reducer calls `repository.refresh()`	Move to `FactsDataMiddleware.process(Refresh)`
Reducer emits a side effect	Middleware's job; remove `emit` from the reducer
Reducer uses `System.currentTimeMillis()`	Pass the time through the intent payload
Reducer throws on unknown combinations	Fold into state validation in a middleware; reducer is total
`when` has an `else` branch	Remove; let the compiler enforce exhaustiveness
Reducer helper is `suspend`	Move to a middleware
Branch unconditionally returns `copy()`	Add a no-op reference check

Asynchronous work lives in middlewares. Repositories, use cases, debouncing, retries with backoff, analytics, SavedStateHandle persistence, keyed per-entity cancellation — every one of those belongs to a middleware, not the reducer. The reducer stays a pure function over (State, Intent); the runtime, through the middleware layer, handles I/O and dispatches result intents (FactsReceived, FactsLoadFailed, BookmarkConfirmed) back into the store for the reducer to fold into state. A middleware is the shape that accepts suspend, scope.launch, Flow operators, and runTest — all of which the reducer refuses.

Non-determinism is the other category. System.currentTimeMillis(), UUID.randomUUID(), Random.nextInt(), and any @Inject val clock: Clock all break time-travel replay and fail the property-based fuzz test every feature ships. The discipline is to pass time and identifiers through the intent payload — FactsReceived(facts, fetchedAt) — so that replaying a captured intent stream reproduces the bug exactly, in milliseconds, against the pure reducer. The same applies to error mapping: Throwable.toUiText() lives in :core:designsystem, takes no Android Context, and stays pure so the reducer can call it without tainting the tier. Intents are the only currency that crosses the boundary; the reducer never calls out, and the middleware never writes in.

Rule: if a helper needs suspend, a clock, or a repository, it belongs to a middleware.

Where to go next

The Android Testing Pyramid That Strict MVI Unlocks

Ouday khaled — Tue, 21 Apr 2026 16:50:54 +0000

80% of your presentation tests live in the reducer tier and run in 5ms. The other four tiers exist, but they are narrow on purpose — device-bound work is the rarest thing the pyramid measures. Strict MVI is what makes that shape possible in the first place.

Five tiers at a glance

The shape is fixed: a wide reducer base, a thinner middleware band, a narrow store-integration strip, a screen layer, and a handful of macrobenchmarks on top. A mid-sized feature produces 30–50 reducer tests, 10–20 middleware tests, 5–10 store integration tests, 5–10 screen tests, and 2–4 macrobenchmarks. Wall-clock budgets are equally uneven: under a second for the reducer tier, a few seconds for middleware, about five seconds for integration, and device-bound time for everything above.

If a feature has fewer reducer tests than middleware and integration combined, the reducer is doing too little or authors default to integration out of habit. The pyramid also diagnoses the codebase, not only the test suite. The tier where an assertion lives is a proof of what the code couples to: a state-shape claim that requires a coroutine dispatcher hints at reducer impurity; a middleware test that touches Compose hints at leaking presentation concerns into async orchestration. The rule for each new behaviour is to write the lowest-tier test that can prove it, and to move up only when that tier refuses to see the bug.

Rule: write every presentation test at the lowest tier that can prove the behaviour.

Reducer tier — 80% of tests

class FactsReducerTest {

    @Test
    fun `Refresh on idle sets isRefreshing and clears error`() {
        val out = FactsReducer.reduce(
            state = FactsState(error = UiText.Raw("stale")),
            intent = FactsIntent.Refresh,
        )
        assertTrue(out.state.isRefreshing)
        assertNull(out.state.error)
        assertTrue(out.followUps.isEmpty())
    }

    @Test
    fun `Refresh while already refreshing returns same instance`() {
        val state = FactsState(isRefreshing = true)
        val out = FactsReducer.reduce(state, FactsIntent.Refresh)
        assertSame(state, out.state)
    }

    @Test
    fun `Retry sets loading and emits LoadNextPage follow-up`() {
        val out = FactsReducer.reduce(
            state = FactsState(error = UiText.Raw("x")),
            intent = FactsIntent.Retry,
        )
        assertTrue(out.state.isLoading)
        assertEquals(listOf(FactsIntent.LoadNextPage), out.followUps)
    }
}

Error-to-UiText mappings are the obvious parameterised block:

@RunWith(Parameterized::class)
class FactsReducerErrorMappingTest(
    private val cause: Throwable,
    private val expected: UiText,
) {
    companion object {
        @JvmStatic
        @Parameterized.Parameters(name = "{0} -> {1}")
        fun data() = listOf(
            arrayOf(IOException(), UiText.Resource(R.string.error_network)),
            arrayOf(ServerException(500, "x"), UiText.Resource(R.string.error_server)),
            arrayOf(RuntimeException(), UiText.Resource(R.string.error_unknown)),
        )
    }

    @Test
    fun `FactsLoadFailed maps cause to UiText`() {
        val out = FactsReducer.reduce(FactsState(), FactsIntent.FactsLoadFailed(cause))
        assertEquals(expected, out.state.error)
    }
}

No @Before, no Dispatchers.setMain, no runTest, no MockK, no Turbine, no Hilt. Anything from that list inside a reducer test means the test belongs a tier up. The canonical shape is three tests per intent — happy path, no-op branch with assertSame, and one edge or error branch — plus a parameterised block for error mappings. Follow-up intents get an exact list assertion, not a contains-check; the reducer's follow-up list is a total contract, and any looseness there hides re-entrant loops that only surface in integration later. See https://medium.com/@ouday.khaled/pure-reducers-in-kotlin-why-your-android-unit-tests-should-run-in-5-milliseconds-a4277cea3c38 for the full reducer contract.

Test names follow the BDD pattern <Intent> <condition> <outcome> — Refresh on idle sets isRefreshing and clears error. The intent is the grammatical subject; the entry point into the Store is send(intent), so the failure message reads like the bug report. Every feature also ships a seeded fuzz test that folds 10,000 random intents through the reducer and asserts global invariants — no duplicate facts by id, currentPage >= 1, bookmarkLoadingIds stays an ImmutableSet. Because the reducer is pure, the whole fuzz run clears in under 100 ms and surfaces invariant bugs that would take a week to reproduce manually.

Rule: if a reducer test imports a coroutine utility, delete the import or move the test.

Middleware tier with Turbine

A middleware test wires three inputs — an Intent, a fake repository, and a State snapshot — and asserts two outputs: the list of dispatched intents and the list of emitted effects. Each arrow is a contract point.

@Test
fun `ToggleBookmark success dispatches Started then Confirmed`() = runTest {
    val dispatched = mutableListOf<FactsIntent>()
    val emitted = mutableListOf<FactsEffect>()
    middleware.process(
        intent = FactsIntent.ToggleBookmark("a"),
        state = FactsState(facts = persistentListOf(CatFact(id = "a", isBookmarked = false))),
        scope = backgroundScope,
        dispatch = { dispatched += it }, emit = { emitted += it; true },
    )
    advanceUntilIdle()

    assertEquals(FactsIntent.BookmarkStarted("a"), dispatched[0])
    assertTrue(dispatched[1] is FactsIntent.BookmarkConfirmed)
    assertTrue(emitted.isEmpty())
}

Cancellation keys, debounce, and throttle are the tier's hardest work, and advanceTimeBy makes them deterministic:

@Test
fun `rapid ToggleBookmark cancels the in-flight job`() = runTest {
    fakeRepo.bookmarkDelay = 200L
    val dispatched = mutableListOf<FactsIntent>()
    val state = FactsState(facts = persistentListOf(CatFact(id = "a", isBookmarked = false)))

    middleware.process(FactsIntent.ToggleBookmark("a"), state, backgroundScope, { dispatched += it }, { true })
    advanceTimeBy(50L)
    middleware.process(FactsIntent.ToggleBookmark("a"), state, backgroundScope, { dispatched += it }, { true })
    advanceUntilIdle()

    val confirmed = dispatched.filterIsInstance<FactsIntent.BookmarkConfirmed>()
    assertEquals(1, confirmed.size)
}

Use StandardTestDispatcher with setMain/resetMain, backgroundScope from runTest, and advanceTimeBy/advanceUntilIdle for debounce and cancellation. Prefer a real use case over a fake repository to mocking the use case — the fake is the observable surface, and every expectation lands on it rather than on the use case's internals. Middleware tests never construct their own CoroutineScope: a hand-rolled CoroutineScope(Job()) keeps running after the test and leaks state across cases.

Three async surfaces live here and nowhere else: debounced input, keyed per-entity cancellation, and onStart pipelines that observe a repository Flow. A SearchChanged test advances the virtual clock past 350ms and confirms exactly one SearchQueryCommitted emerges, not three. A bookmark test fires two ToggleBookmark("a") intents 50ms apart and asserts that only one BookmarkConfirmed("a") lands. An onStart test emits into the fake repository's Flow and asserts a FactsReceived dispatch follows. If a middleware test tries to assert on store.state, it is already wearing two hats and belongs a tier up.

Rule: capture dispatch and emit as lists; assert the lists, not the middleware's internals.

Store integration tier

@Test
fun `Refresh success updates state with facts`() = runTest {
    fakeRepo.nextRefreshReturns(listOf(CatFact(id = "a", fact = "a", isBookmarked = false)))
    store.state.test {
        assertEquals(FactsState(), awaitItem())
        store.send(FactsIntent.Refresh)
        assertTrue(awaitItem().isRefreshing)
        val final = expectMostRecentItem()
        assertFalse(final.isRefreshing)
        assertEquals(1, final.facts.size)
        cancelAndIgnoreRemainingEvents()
    }
}

Real reducer, real middlewares, fake repository, Turbine on store.state and store.effects. Verify the endpoints — initial state, final state via expectMostRecentItem(), one effect per effect kind. Do not assert every intermediate emission; that is a brittle reimplementation of the reducer test. SavedStateHandle restore is a store test, not a middleware test: the contract crosses both collaborators, and the test proves that constructing a new FactsStoreImpl with a pre-seeded SavedStateHandle restores searchInput and currentPage into the first state.value.

Keep this tier deliberately narrow. One happy path per feature and one failure per async intent family is enough — eight tests is generous. Middleware ordering regressions surface here as telemetry firing against pre-reducer state or save-state capturing the wrong snapshot, and the fix is always a single-line reorder in the Store's middlewares = listOf(...) list. Anti-patterns like state-in-effect or SharedFlow for effects also surface here as lost emissions when Turbine times out on store.effects.test { awaitItem() }; those belong in https://medium.com/@ouday.khaled/10-mvi-anti-patterns-senior-android-reviewers-reject-on-sight-44bd94fd5358.

Rule: store tests prove the wiring, not the branches.

Screen and macrobenchmark

@Test
fun `clicking fact card dispatches FactClicked with correct id`() {
    val intents = mutableListOf<FactsIntent>()
    composeRule.setContent {
        CatFactTheme {
            FactsScreen(state = FactsState(facts = persistentListOf(fact)), onIntent = { intents += it })
        }
    }
    composeRule.onNodeWithTag("fact_card_abc").performClick()
    assertEquals(listOf(FactsIntent.FactClicked("abc")), intents)
}

Compose tests drive the Screen with a fabricated State and a single onIntent capture list. One interactive element, one assertion — the list asserts both which intent and its payload. The Route is omitted by design; Route wiring is covered by the store tier and by the flagship https://medium.com/@ouday.khaled/the-strict-mvi-playbook-how-staff-android-engineers-structure-jetpack-compose-at-scale-410a8717f1f7.

Macrobenchmark occupies the tip. Four benchmarks cover the hot paths per intent family:

@Test
fun scrollFactsList() = benchmarkRule.measureRepeated(
    packageName = "com.catfact.app",
    metrics = listOf(FrameTimingMetric()),
    startupMode = StartupMode.WARM, iterations = 5,
    setupBlock = { /* open app, seed list */ },
) {
    device.findObject(By.res("facts_list")).fling(Direction.DOWN)
}

A TraceSectionMetric("FactsReducer.reduce") over 100µs per reduction is a regression; a frame spike on resume points at effect-channel overflow during the stopped window. Scroll regressions usually trace back to a reducer allocating a new ImmutableList on every emission, which the no-op detection rule in https://medium.com/@ouday.khaled/pure-reducers-in-kotlin-why-your-android-unit-tests-should-run-in-5-milliseconds-a4277cea3c38 prevents. The baseline profile covers the full intent journey — refresh, search, toggle, navigate, retry — not only cold start and scroll, so a user-critical intent that regresses by five frames shows up before the next release train.

Rule: device-bound tests count the render, not the branches.

Coverage targets

Layer	Min line coverage
Reducer	100% — pure, no excuse
Middleware	85% — branches around cancellation
Store integration	70% — happy + 1 failure per feature
Screen	≥ 1 intent-dispatch test per element

The reducer and middleware tiers combine to 85%+ of the presentation surface — verified before a device ever boots. The store tier picks up the wiring gaps. Screen tests are counted by interactive elements, not by lines, because a Compose node with no dispatch point proves nothing; coverage tools register the click handler as executed whether or not the intent it dispatches is correct.

Wire these thresholds into jacocoCombinedReport and fail the build under them. A pure reducer that drops below 100% means a branch was added without a test; a middleware below 85% usually means a cancellation path slipped through the catch (e: CancellationException) { throw e } rethrow and landed in state.error. One follow-up practice pays back twice: every reproduced bug ships with a captured intent sequence that replays through the reducer in milliseconds, and that capture lands in the commit as a regression test at the base tier.

Rule: the build enforces the pyramid, not the author.

Where to go next

The Strict-MVI Playbook — the architecture that makes this pyramid possible.
Pure Reducers in Kotlin — the 5ms base tier, in depth.
10 MVI Anti-Patterns Reviewers Reject on Sight — what makes the store tier lie.

10 MVI Anti-Patterns Senior Android Reviewers Reject on Sight

Ouday khaled — Tue, 21 Apr 2026 16:50:43 +0000

Strict MVI on Android fails in the same ten ways in every codebase. This article is the pocket cheat sheet senior reviewers keep open during a pull-request pass. Each entry is a smell, a bad snippet, a good snippet, and one sentence explaining why it blocks the PR.

The ten

#	Anti-pattern	Root cause
1	The God Intent	Reducer authority dissolved
2	Fat State	State shape sprawling
3	Side-Effecting Reducer	Reducer authority dissolved
4	Effect Used as Intent	Contract channel misused
5	Named Public Methods on the Store	Contract vocabulary duplicated
6	State-in-Effect via `Navigate*`	Contract channel misused
7	`SharedFlow` for Effects	Runtime drops emissions
8	`onEvent` Wrapper Type	Contract vocabulary duplicated
9	Middleware Mutating State Directly	Reducer authority dissolved
10	Swallowed `CancellationException`	Runtime leaks async detail

Three root causes cover all ten. Something other than the reducer is authoring state (1, 3, 9). The contract channel or vocabulary is being duplicated or misused (4, 5, 6, 8). The runtime is leaking async detail that belongs inside a middleware (7, 10). Fat State (2) is the odd one out — a design smell that precedes any of the other nine. Each entry below is one concrete instance with the bad shape and the shape reviewers accept.

1. The God Intent

An Intent.Update(state) dissolves the reducer's authority. Every call site becomes a state author, and replay is impossible because the intent carries the result instead of the cause.

sealed interface FactsIntent : MviIntent {
    data class Update(val state: FactsState) : FactsIntent
    data class MergeInto(val partial: FactsState.() -> FactsState) : FactsIntent
}

sealed interface FactsIntent : MviIntent {
    data object Refresh : FactsIntent
    data object DismissError : FactsIntent
    data class SearchChanged(val query: String) : FactsIntent
    data class ToggleBookmark(val factId: String) : FactsIntent
    // internal (middleware → reducer)
    data class FactsReceived(val facts: ImmutableList<CatFact>) : FactsIntent
}

Why reviewers block it. Intents must describe cause, not effect; the reducer is the only place allowed to derive new state.

2. Fat State

A single state with 30-plus fields forces copy-on-update across unrelated concerns and produces a 300-line reducer no one can read.

data class FactsState(
    val searchQuery: String, val searchOffset: Int, val searchHasMore: Boolean,
    val searchIsLoading: Boolean, val searchError: UiText?,
    val feedItems: ImmutableList<Feed>, val feedRefreshing: Boolean, val feedPage: Int,
    val feedError: UiText?,
    val bookmarkLoadingIds: ImmutableSet<String>, val bookmarkError: UiText?,
    val settingsTheme: ThemeMode, val settingsDynamicColor: Boolean,
    val settingsError: UiText?, /* ...26 more fields... */
)

// Split along feature seams, scoped to the same ViewModelComponent.
interface FeedStore       : MviStore<FeedState, FeedIntent, FeedEffect>
interface FilterStore     : MviStore<FilterState, FilterIntent, FilterEffect>
interface BookmarksStore  : MviStore<BookmarksState, BookmarksIntent, BookmarksEffect>

Why reviewers block it. Fifteen fields is the soft ceiling; past it, unrelated concerns co-update in the same reducer branch and tests grow 30-field fixtures.

3. Side-Effecting Reducer

object FactsReducer : MviReducer<FactsState, FactsIntent> {
    override fun reduce(state, intent) = when (intent) {
        FactsIntent.Refresh -> {
            repository.refresh()
            logger.i("refresh")
            eventTracker.trackEvent("refresh")
            Reduction(state.copy(isRefreshing = true))
        }
    }
}

object FactsReducer : MviReducer<FactsState, FactsIntent> {
    override fun reduce(state, intent) = when (intent) {
        FactsIntent.Refresh -> Reduction(state.copy(isRefreshing = true))
        // ... one branch per intent, no collaborators ...
    }
}

Why reviewers block it. A reducer that calls a repository or logger is no longer pure, cannot be unit-tested without mocks, and breaks object purity by demanding injection.

4. Effect Used as Intent

A list of facts is renderable, so it is state — never a one-shot effect. Pushing state through the effect channel bypasses the reducer and loses data on rotation.

sealed interface FactsEffect : MviEffect {
    data class UpdateFacts(val facts: ImmutableList<CatFact>) : FactsEffect
    data class SetLoading(val loading: Boolean) : FactsEffect
    data class NavigateToDetail(val fact: CatFact) : FactsEffect
}

sealed interface FactsIntent : MviIntent {
    data class FactsReceived(val facts: ImmutableList<CatFact>) : FactsIntent
}
sealed interface FactsEffect : MviEffect {
    data class NavigateToDetail(val factId: String) : FactsEffect
}

Why reviewers block it. Effects are one-shot and non-renderable; anything the UI can draw belongs in StateFlow<State>, and navigation effects carry identifiers only.

5. Named Public Methods on the Store

class FactsStoreImpl : BaseMviStore<...>() {
    fun refresh() = send(FactsIntent.Refresh)
    fun toggleBookmark(id: String) = send(FactsIntent.ToggleBookmark(id))
    fun onSearchQueryChanged(q: String) = send(FactsIntent.SearchChanged(q))
}

// Route.kt
FactsScreen(
    state = state,
    onIntent = store::send,   // the only entry point
    modifier = modifier,
)

Why reviewers block it. Named methods re-introduce a parallel API on top of MVI; the contract is the intent type, not the Store's method list.

6. State-in-Effect via `Navigate*(snapshot)`

sealed interface FactsEffect : MviEffect {
    data class NavigateToDetail(val fact: CatFact) : FactsEffect
}

sealed interface FactsEffect : MviEffect {
    data class NavigateToDetail(val factId: String) : FactsEffect
}

Why reviewers block it. The destination screen binds to a payload that goes stale the moment the user returns; navigation effects must pass identifiers so the detail store fetches its own data.

7. `SharedFlow` for Effects

SharedFlow(replay = 0) drops every emission before a subscriber attaches — navigation and snackbars disappear on configuration change or transition.

private val _effects = MutableSharedFlow<FactsEffect>(replay = 0, extraBufferCapacity = 1)
val effects: SharedFlow<FactsEffect> = _effects.asSharedFlow()

private val _effects = Channel<FactsEffect>(Channel.BUFFERED)
val effects: Flow<FactsEffect> = _effects.receiveAsFlow()

Why reviewers block it. A Channel(BUFFERED) queues up to 64 effects until the Route attaches and delivers each exactly once; SharedFlow silently drops them or duplicates them if replay is raised.

8. `onEvent` Wrapper Type

data class FactsEvent(val intent: FactsIntent)

@Composable
fun FactsScreen(state: FactsState, onEvent: (FactsEvent) -> Unit, /* ... */)

onEvent(FactsEvent(FactsIntent.Refresh))

@Composable
fun FactsScreen(state: FactsState, onIntent: (FactsIntent) -> Unit, modifier: Modifier)

onIntent(FactsIntent.Refresh)

Why reviewers block it. A wrapper type duplicates the contract in call sites, tests, and analytics; the intent type is the contract and nothing should obscure it.

9. Middleware Mutating State Directly

class FactsDataMiddleware(private val store: FactsStoreImpl) : MviMiddleware<...> {
    override fun process(intent, state, scope, dispatch, emit) {
        store._state.update { it.copy(isLoading = true) }
    }
}

override fun process(intent, state, scope, dispatch, emit) {
    dispatch(FactsIntent.LoadingStarted)   // reducer owns isLoading
}

Why reviewers block it. The reducer is the sole state authority; any bypass breaks the "state ⇐ intent" invariant and makes replay impossible.

10. Swallowed `CancellationException`

scope.launch {
    try {
        val result = longRunningCall()
        dispatch(FactsIntent.Received(result))
    } catch (e: Exception) {
        dispatch(FactsIntent.Failed(e))
    }
}

scope.launch {
    try {
        val result = longRunningCall()
        dispatch(FactsIntent.Received(result))
    } catch (e: CancellationException) { throw e }
    catch (e: Exception) { dispatch(FactsIntent.Failed(e)) }
}

Why reviewers block it. A swallowed CancellationException turns cooperative cancellation into a failure stored as state.error, leaving a stale banner for an operation the user already cancelled.

Rule: every anti-pattern on this list has the same root cause — something other than an intent is authoring state, or something renderable is travelling as an effect.

Review-meeting pocket guide

Scan for	Why it blocks the PR
`Intent.Update(State)`, `Intent.Set*`, or any intent whose payload is a full state snapshot.	The intent is state-in-disguise; the reducer loses authority and replay becomes impossible.
A reducer that imports a repository, logger, analytics client, or clock.	Purity is gone; unit tests need mocks; time-travel and property-based fuzz tests break.
`SharedFlow` anywhere — intents or effects — on a Store.	Emissions drop before a subscriber attaches; navigation and snackbars vanish on configuration change.
Named methods on the Store other than `send(...)`; a Screen signature with more than one lambda besides `modifier`.	A parallel API reappears on top of the intent type; analytics, tests, and capture replay split across two surfaces.
`catch (e: Exception)` without a preceding `catch (e: CancellationException) { throw e }`, including before any `withTimeout`.	Cooperative cancellation turns into a stored failure; stale error banners persist for operations the user already cancelled.
`suspend fun process(...)` in a middleware, or a bounded intent buffer with `check(tryEmit)`.	A suspending middleware blocks the chain; a bounded intent buffer turns normal bursts into crashes.
`LaunchedEffect(Unit) { store.effects.collect { } }` without `repeatOnLifecycle(STARTED)`.	Navigation effects fire into the back stack; snackbars land in hidden scaffolds on rotation.
Raw `Color(0xFF...)`, raw `dp` literals, raw user-visible strings; missing `@Stable` on `Intent` or `Effect` sealed roots.	Design-system drift, non-localisable strings, and Compose skipping collapses on the intent lambda.
A feature test folder with no `FactsReducerTest.kt` equivalent.	Every intent deserves three reducer tests before any middleware or screen test; the pyramid has no base.
Middleware injecting `MviStore`; middleware calling `store._state.update`.	Hilt cycle and bypass of the reducer; the `state ⇐ intent` invariant collapses.

The scan is ordered by the two questions that catch the most slips: what is authoring state that is not the reducer, and what is travelling through the effect channel that the UI needs to render. Both questions are answerable in under a minute on any diff, and the counterpart snippet in the matching section is the fix — no design meeting required.

Rule: if any row above fires, link this article in the review comment and paste the counterpart snippet from the matching section.

Where to go next

The Strict-MVI Playbook: How Staff Android Engineers Structure Jetpack Compose at Scale

Ouday khaled — Tue, 21 Apr 2026 16:50:19 +0000

A strict-MVI feature exposes exactly one public entry point, send(intent), and one observable output, StateFlow<State>. Everything else — reducer, middlewares, channels, cancellation keys — is an implementation detail negotiated behind that contract. This playbook is the staff-level brief on how to make that choice survive the tenth engineer, the fiftieth screen, and the fourth rewrite.

The contract: three sealed types

@Immutable
data class FactsState(
    val facts: ImmutableList<CatFact> = persistentListOf(),
    val isLoading: Boolean = false,
    val isLoadingMore: Boolean = false,
    val isRefreshing: Boolean = false,
    val error: UiText? = null,
    val searchInput: String = "",
    val searchQuery: String = "",
    val currentPage: Int = 1,
    val hasMorePages: Boolean = true,
    val bookmarkLoadingIds: ImmutableSet<String> = persistentSetOf(),
) : MviState

@Stable
sealed interface FactsIntent : MviIntent {
    data object Refresh : FactsIntent
    data object LoadNextPage : FactsIntent
    data class SearchChanged(val query: String) : FactsIntent
    data class ToggleBookmark(val factId: String) : FactsIntent
    data class FactClicked(val factId: String) : FactsIntent
    data object FetchRandomFact : FactsIntent
    data object DismissError : FactsIntent
    data object Retry : FactsIntent
}

@Stable
sealed interface FactsEffect : MviEffect {
    data class NavigateToDetail(val factId: String) : FactsEffect
    data class ShowSnackbar(val message: UiText) : FactsEffect
}

interface FactsStore : MviStore<FactsState, FactsIntent, FactsEffect>

State is a photograph of what the UI currently shows. Intent describes what happened — a gesture, a lifecycle callback, or a middleware finishing an async call. Effect is a one-shot message the UI performs and forgets. Renderable errors live in State.error; effects cannot be replayed on rotation.

Intents divide into three buckets. Keeping them visually separated in the contract file turns the trilogy into a readable specification rather than an implementation detail:

Bucket	Source	Naming	Examples
User gesture	UI tap / swipe / text	verb past-tense, `<Noun>Clicked`	`Refresh`, `DismissError`, `FactClicked(id)`, `SearchChanged(q)`
Lifecycle / system	`LaunchedEffect`, connectivity, permissions	`<Event>Happened`	`ScreenResumed`, `ConnectivityChanged(Boolean)`, `PermissionGranted`
Internal	Middleware completing async work	`<Noun>Received` / `<Noun>Failed`	`FactsReceived(List)`, `FactsLoadFailed(Throwable)`, `BookmarkConfirmed(id)`

Three smells tell you the contract is drifting:

Smell	What it hides	Fix
`Intent.SetLoading(Boolean)`	State mutation disguised as user input	Neutral intents (`Refresh`, `LoadNextPage`); the reducer derives loading.
`Effect.UpdateFacts(List)`	State pushed through the effect channel	Dispatch `Intent.FactsReceived(list)`; the reducer writes state.
`State.shouldNavigateTo: Boolean`	Navigation as persistent state	Fire `Effect.NavigateTo*` once; the Route handles it.
Fifteen effect kinds in one feature	Effects absorbing work that belongs to state	Collapse to five: `Navigate`, `Show`, `Launch*`, period.
`Intent.NavigateToDetail(id)`	Imperative intent stealing the reducer's authority	Rename to `FactClicked(id)`; the reducer decides the consequence.
`State.isNavigatingToDetail`	Navigation as a renderable field	Emit `Effect.NavigateToDetail(id)` once; never persist the transition.
`Effect.SetLoading(true)`	One-shot wrapping a state flip	Dispatch an intent; the reducer toggles `isLoading`.

A healthy effect inventory stays in one of five slots. Anything outside this set is a design smell, not an expansion of the contract:

Effect kind	Use for	Bad smell
`NavigateTo*`	Forward navigation only.	Back navigation belongs to the UI's `onBack`.
`ShowSnackbar(UiText)`	Transient messages that auto-dismiss.	Error banners belong in state.
`ShowToast(UiText)`	Material-less alerts (rare).	Prefer a snackbar.
`Launch(Intent)` / `LaunchUrl`	External intents, share sheet, deep links.	Validate at the effect boundary.
`Vibrate` / `PlaySound`	Haptics and audio the Store owns.	Often a Compose helper fits better.
`RequestPermission`	Prompting the user at the system boundary.	Cache the result as an intent; never re-ask blindly.

Rule: the trilogy is a public API — review its naming, ordering, and payloads like one.

The runtime: Store, Reducer, Middleware

UI ──intent──▶  Store  ──(state, intent)──▶  Reducer (pure)
                │                             (state', followUps)
                ├───▶  Middleware₁ (repository, mappers)
                ├───▶  Middleware₂ (analytics)
                └───▶  Middleware₃ (SavedStateHandle persistence)
                        │
                        └─▶ dispatches more intents back into the Store
                state: StateFlow<State>       effects: Flow<Effect>

The Store is a thin runtime wiring the reducer and middleware list to a StateFlow<State> and a Channel<Effect>. The reducer is a pure (State, Intent) -> Reduction. Middlewares are non-suspending; they launch async work into the Store's scope and feed results back as internal intents so the reducer stays the sole authority on state transitions.

abstract class BaseMviStore<S : MviState, I : MviIntent, E : MviEffect>(
    initialState: S,
    private val reducer: MviReducer<S, I>,
    private val middlewares: List<MviMiddleware<S, I, E>>,
) : ViewModel(), MviStore<S, I, E> {

    private val _state = MutableStateFlow(initialState)
    override val state: StateFlow<S> = _state.asStateFlow()

    private val effectChannel = Channel<E>(EFFECT_BUFFER)
    override val effects: Flow<E> = effectChannel.receiveAsFlow()

    private val intentChannel = Channel<I>(Channel.UNLIMITED)

    // ... unchanged ...

    private fun handle(intent: I) {
        val reduction = reducer.reduce(_state.value, intent)
        if (reduction.state !== _state.value) _state.value = reduction.state
        reduction.followUps.forEach(::send)
        middlewares.forEach { mw ->
            mw.process(intent, _state.value, viewModelScope, ::send, ::postEffect)
        }
    }

    companion object { private const val EFFECT_BUFFER = 64 }
}

What the runtime guarantees, and what it deliberately does not:

Guaranteed	Not guaranteed
Intents processed in order on the main thread.	Async work from middleware completes before the next intent arrives.
Reducer has exclusive access to state during `reduce`.	Dispatched intents inside a middleware are handled within the current intent chain.
Middlewares see post-reducer state in `process`.	`emit(Effect)` always reaches the Route — overflow drops silently.
Effects are FIFO and delivered exactly once to the single collector.	Middleware-launched coroutines finish on any particular dispatcher.

Runtime choices worth pinning down so nobody relitigates them in a review:

Intent queue — Channel<I>(Channel.UNLIMITED) with trySend. The consumer is a microsecond-speed pure reducer on the main thread; human producers plus bounded middleware follow-ups cannot outrun it. A bounded queue with check(tryEmit) converts normal bursts into crashes.
Effect channel — Channel<E>(64) with trySend. Sixty-four covers any sane feature's stopped-lifecycle window. Overflow drops silently because overflow signals a middleware emitting state-shaped noise through the wrong channel.
Dispatcher — Dispatchers.Main.immediate via viewModelScope. Reducer, intent consumption, and process all run there. Room and Retrofit switch internally, so middleware-launched coroutines rarely need withContext.
Thread confinement — one consumer on the intent channel means the reducer never sees concurrent access. Mutex, synchronized, and @Volatile in feature code are all signals that the abstraction is being bypassed.
Middleware ordering — Data dispatches follow-ups first, SavedState captures the post-reducer snapshot next, Telemetry runs last against the final committed state.

Three middleware archetypes cover more than 90% of features. A new middleware should fit one of them or earn a paragraph in the PR description explaining why it does not:

Archetype	Responsibility	Owns
`DataMiddleware`	Drives the feature's async world. Observes repository Flows in `onStart`, reacts to intents in `process`, dispatches internal `Received` / `Failed` intents, owns cancellation-key maps.	Use cases, Flow pipelines, `withTimeout`, keyed jobs.
`SavedStateMiddleware`	Persists the restorable subset of state after the reducer commits. Writes on every intent; reads once at initial-state restore.	`SavedStateHandle`, `toSaved()` / `toFactsState()` extensions.
`TelemetryMiddleware`	Records analytics keyed on intent against the final committed state. Runs last so events match what the UI rendered.	`EventTracker`, per-intent mapping table, session ids.

Rule: the reducer runs before middlewares, the reducer is pure, and the reducer never sees a coroutine.

Twelve non-negotiables

The rules below are the minimum bar for a feature to pass code review. They are enforced by Konsist tests in CI, not by taste:

#	Rule
1	Exactly one `Store` class per screen, extending `BaseMviStore`.
2	Reducer is a pure top-level `object`. No `@Inject`, no `suspend`, no Store reference.
3	All user inputs route through `store.send(intent)`. No named public methods.
4	`*Screen` takes `state: FactsState` and exactly one `onIntent: (FactsIntent) -> Unit`.
5	`Effect` uses `Channel(Channel.BUFFERED).receiveAsFlow()`. Never `SharedFlow`, never `LiveData`.
6	Restorable subset (`searchInput`, `currentPage`, selected-tab, draft text) saved via `SavedStateHandle`; transient fields (`isLoading`, `bookmarkLoadingIds`) are not.
7	User-cancellable side effects are keyed by entity id and de-duplicated in the middleware.
8	Intent handling is idempotent — re-sending the same intent N times converges on the same state.
9	User-visible errors live in `State.error: UiText?`. Effects are only `Navigate`, `Show`, `Launch*`.
10	Analytics go through a dedicated `TelemetryMiddleware`, not in the reducer.
11	`@HiltViewModel` annotates the Store implementation class (named `Store`, not `ViewModel`); UI reads `store.state`.
12	Composition-root wiring (Hilt, Navigation 3, Room, Retrofit, design system, benchmark) is inherited from the engineering skill pack.

Rule 3 rejects the most common regression — reintroducing named public methods (store.refresh(), store.toggleBookmark(id)) on top of send. When that happens, the intent contract stops being the single source of truth, analytics lose their hook, and test captures degrade into method-call transcripts. Rule 7 is the sleeper: keyed cancellation lives in the middleware so the reducer stays free of Job handles. Konsist enforces the mechanical half of the list:

@Test
fun `reducers are objects in the feature package`() {
    Konsist.scopeFromProject().classes()
        .filter { it.name.endsWith("Reducer") }
        .assertTrue { it.hasModifier(KoModifier.OBJECT) || it.hasModifier(KoModifier.ABSTRACT) }
}

@Test
fun `reducers do not inject anything`() {
    Konsist.scopeFromProject().classes()
        .filter { it.name.endsWith("Reducer") }
        .assertTrue { it.primaryConstructor == null || it.primaryConstructor!!.parameters.isEmpty() }
}

@Test
fun `stores expose only send and the StateFlow and Flow accessors`() {
    // ... unchanged ...
}

See https://medium.com/@ouday.khaled/10-mvi-anti-patterns-senior-android-reviewers-reject-on-sight-44bd94fd5358 for the ten reviewer-blocked variants. Those that slip through without CI enforcement:

Pattern	What to block
`Intent.Update(state: State)`	Reducer-shaped intent that turns the contract into a field-setter API.
Forty-field `FactsState` with mixed concerns	Split into sub-stores or `Mutation` composition before any more fields land.
`fun refresh()` on the Store next to `send`	Named public method regrowing on top of the intent channel.
`Effect.UpdatePaging(snapshot)`	State shipped through the effect channel; rotation drops the UI back to empty.
`SharedFlow` swapped in for effects	Lost emissions on missing subscriber, impossible to debug.
`FactsEvent` wrapping `FactsIntent`	Duplicated contract; the second type always drifts from the first.
Middleware writing `_state.value`	Reducer authority bypassed; every invariant the reducer enforces becomes optional.

Rule: treat every deviation from the twelve as a PR block, not a discussion.

Directory layout

feature/facts/src/main/java/com/catfact/feature/facts/
├── FactsStore.kt              ← interface + @HiltViewModel implementation
├── FactsContract.kt           ← sealed State / Intent / Effect (one file)
├── FactsReducer.kt            ← pure object — unit tested with JUnit
├── middleware/
│   ├── FactsDataMiddleware.kt
│   ├── FactsTelemetryMiddleware.kt
│   └── FactsSavedStateMiddleware.kt
└── presentation/
    ├── FactsRoute.kt          ← @Composable — hiltViewModel, collectAsStateWithLifecycle, effects
    ├── FactsScreen.kt         ← @Composable — (state, onIntent, modifier)
    └── components/

Each file has one concern and one expected test suite:

File	Owns	Test suite
`FactsContract.kt`	Sealed `State`, `Intent`, `Effect`. Process-death keys.	Contract smoke test — every intent has a reducer branch.
`FactsReducer.kt`	`(State, Intent) -> Reduction`. Exhaustive `when`.	Pure JUnit. Three tests per intent: happy, error, edge.
`FactsStore.kt`	`BaseMviStore` subclass, Hilt binding, middleware order.	Store integration with real middlewares + fake repo.
`middleware/*.kt`	One async concern each — data, saved state, telemetry.	One middleware at a time + MockK + Turbine + `runTest`.
`presentation/FactsRoute.kt`	Hilt, `collectAsStateWithLifecycle`, effect collection.	Compose test asserts effect → callback mapping.
`presentation/FactsScreen.kt`	Stateless `(state, onIntent, modifier)`. Previews.	Compose test with captured-intent list.
`presentation/components/`	Feature-local UI pieces.	Rendered via previews and screenshot tests.

Hilt binding is one module per feature, flat and predictable:

@Module
@InstallIn(ViewModelComponent::class)
abstract class FactsStoreModule {
    @Binds
    abstract fun bindFactsStore(impl: FactsStoreImpl): FactsStore
}

Middlewares are @ViewModelScoped and compose use cases only. Direct repository injection leaks data-layer types into presentation; the sole exception is FactsSavedStateMiddleware, which injects SavedStateHandle. Detail screens with runtime arguments use @AssistedInject plus @HiltViewModel(assistedFactory = ...).

Scope in the module graph matters as much as scope inside the feature. App-scoped concerns — authentication, connectivity, theme — never cross into a feature's reducer or UI; they live behind a Flow<Domain> use case injected into a middleware:

Concern	Layer	Exposes	Consumed by
`SessionStore`	`:core:session`, `@Singleton`	`Flow<AuthStatus>` via `ObserveAuthStatusUseCase`	Feature's `DataMiddleware` in `onStart`.
`ConnectivityStore`	`:core:connectivity`, `@Singleton`	`Flow<Connectivity>` via `ObserveConnectivityUseCase`	Feature middleware; reducer handles the internal intent.
`ThemeStore`	`:feature:settings` plus `SettingsRepository`	`Flow<ThemeMode>`	`MainActivity` reads directly to drive `CatFactTheme`.
`FactsStore`	`:feature:facts`, `@HiltViewModel`	`state: StateFlow`, `effects: Flow`, `send(intent)`	`FactsRoute` only.

An app-scoped store injected into a feature reducer is a review block. Cross-feature coordination happens through use cases or through navigation, never through shared state.

Rule: a reviewer should open a feature folder and know which file hides the bug before reading a line.

Compose: Route versus Screen

@Composable
fun FactsRoute(
    onNavigateToDetail: (String) -> Unit,
    onShowSnackbar: (String) -> Unit,
    modifier: Modifier = Modifier,
    store: FactsStoreImpl = hiltViewModel(),
) {
    val state by store.state.collectAsStateWithLifecycle()
    val onIntent = remember<(FactsIntent) -> Unit>(store) { store::send }
    val currentOnNavigate by rememberUpdatedState(onNavigateToDetail)
    val currentOnSnackbar by rememberUpdatedState(onShowSnackbar)
    val context = LocalContext.current
    val lifecycleOwner = LocalLifecycleOwner.current

    LaunchedEffect(store, lifecycleOwner) {
        lifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
            store.effects.collect { effect ->
                when (effect) {
                    is FactsEffect.NavigateToDetail -> currentOnNavigate(effect.factId)
                    is FactsEffect.ShowSnackbar -> currentOnSnackbar(effect.message.resolve(context))
                }
            }
        }
    }

    FactsScreen(state = state, onIntent = onIntent, modifier = modifier)
}

The Route owns every Android dependency the Screen must not touch: Hilt injection, lifecycle collection, UiText resolution, navigation callbacks. Two details carry most of the correctness budget — repeatOnLifecycle(STARTED) is mandatory, and exactly one collector of store.effects exists app-wide; the channel is single-consumer and a second collector silently splits messages.

Intent dispatch at the leaves uses three shapes depending on the component's ownership:

Situation	Shape	Example
Feature-internal composable (`FactCard`, `FactsContent`)	Pass `onIntent`	`onClick = { onIntent(FactsIntent.ToggleBookmark(fact.id)) }`
Shared design-system component (`BookmarkButton`, `ConnectivityBanner`)	Narrowed callback	`onClick: () -> Unit` — the leaf knows nothing of the feature's intent type
Fixed single-action button (`RetryButton`, `ErrorBanner` dismiss)	Pre-bound intent wrapped in `remember(onIntent)`	`onDismiss = remember(onIntent) { { onIntent(FactsIntent.DismissError) } }`

Screens never accept onRefresh or onToggleBookmark as separate parameters. A naked onClick = { onIntent(FactsIntent.ToggleBookmark(fact.id)) } allocates per recomposition and breaks skipping; wrap every shared-component callback in remember(onIntent, key).

A Compose performance checklist worth pinning to the feature template:

@Immutable on every State data class; @Stable on every Intent and Effect sealed root; @Stable on UiText. One un-annotated sub-type drags the whole tree into unstable.
ImmutableList / ImmutableSet from kotlinx.collections.immutable — never List or Set. Compose skipping relies on reference equality that the interface types break.
collectAsStateWithLifecycle() on the Route, never collectAsState().
rememberUpdatedState on every navigation and snackbar callback the Route owns.
LazyColumn key plus contentType on every list item, without exception.
Accessibility actions modeled as intents — a CustomAccessibilityAction on a row dispatches FactsIntent.ToggleBookmark(id) the same way the tap does.

One preview per meaningful state variant gets the design-review loop off the emulator:

Preview	Seeded state	What it catches
Empty	`FactsState()`	First-launch layout, empty placeholder copy, scroll-container sizing.
Loading	`FactsState(isLoading = true)`	Spinner position, skeleton heights, accessibility labels.
Error banner	`FactsState(facts = …, error = UiText.Raw("boom"))`	Banner layering above content without occluding actions.
Full-screen error	`FactsState(error = UiText.Raw("boom"))`	Retry affordance, illustration sizing, dismiss behaviour.
Populated	Ten facts via `TestFixtures.catFact()`	Row density, pagination loader, bookmark toggle visuals.
Paging busy	`FactsState(isLoadingMore = true, hasMorePages = true, facts = …)`	Bottom loader placement and scroll-adjacent spacing.

Rule: the Route handles the world; the Screen is a pure function of state with one output lambda.

Flow and coroutines cheat sheet

Concern	Rule
Public API	`store.send(intent)` only.
State	`StateFlow<State>` produced by the Store.
State update	Inside the reducer, pure. Middlewares never call `.update`.
Side effects	`Channel<Effect>(64)`; middlewares emit via `trySend`.
Async work	`fun process(...)` — non-suspending; launches into `scope`.
Cancellation	`viewModelScope` from `BaseMviStore` cascades. Keyed cancellation maps for per-item work.
Error handling	Middleware rethrows `CancellationException` first, then dispatches `Intent.*Failed(cause)`; reducer decides UI representation.
Intent queue	`Channel<I>(Channel.UNLIMITED)` + `trySend`. Never bounded.

Two choices deserve reinforcement. The intent queue is unbounded on purpose — the consumer is a sub-millisecond reducer on the main thread, the producers are a human tapping plus a handful of middleware pipelines, and unboundedness cannot leak. The effect channel is bounded at 64 because overflow signals pathology, not load: a middleware emitting one effect per state emission is state-in-disguise.

Flow operators in middleware are a short list with sharp edges:

Operator	Use	Example
`.debounce(ms)`	Search input	`searchQueryBus.debounce(350).onEach { dispatch(SearchQueryCommitted(it)) }`
`.distinctUntilChanged()`	Suppress duplicates before every `.onEach { dispatch(...) }`.	Always before dispatch.
`.conflate()`	Only latest, drop intermediates	Connectivity observer → `ConnectivityChanged`.
`.catch { dispatch(Intent.*Failed(it)) }`	Route Flow errors through the state machine	Mandatory on every observation pipeline.
`.launchIn(scope)`	Start pipeline	Use the `scope` from `onStart`.
`flatMapLatest`	Single latest-wins slot (query → result)	Search. Never for N independent per-id slots.

Cancellation keys live in middleware, not in state — jobs are opaque handles. Per-entity work maps the primary key to a Job inside the middleware:

private val bookmarkJobs = mutableMapOf<String, Job>()

override fun process(intent: FactsIntent, state: FactsState, scope: CoroutineScope, ...) {
    when (intent) {
        is FactsIntent.ToggleBookmark -> {
            bookmarkJobs[intent.factId]?.cancel()
            bookmarkJobs[intent.factId] = scope.launch {
                dispatch(FactsIntent.BookmarkStarted(intent.factId))
                try {
                    // ... unchanged ...
                } catch (e: CancellationException) { throw e }
                catch (e: Exception) { dispatch(FactsIntent.BookmarkFailed(intent.factId, e)) }
                finally { bookmarkJobs.remove(intent.factId) }
            }
        }
        else -> Unit
    }
}

scope.launch {
    try {
        val result = withTimeout(5_000L) { api.fetchPage(n) }
        dispatch(FactsReceived(result))
    } catch (e: TimeoutCancellationException) {
        dispatch(FactsLoadFailed(NetworkException.Timeout(e)))
    } catch (e: CancellationException) { throw e }
    catch (e: Exception) { dispatch(FactsLoadFailed(e)) }
}

Two error-handling and dispatcher rules are load-bearing:

CancellationException always rethrows — swallowing it breaks cooperative cancellation for the whole viewModelScope.
TimeoutCancellationException is a CancellationException; convert it to a domain error before the cancellation catch, otherwise the timeout signal vanishes into the rethrow.
Stores, reducers, and middlewares never take Dispatchers.IO; Room and Retrofit switch internally.
Tests bolt on Dispatchers.setMain(StandardTestDispatcher()) in middleware and store suites; reducer tests need no dispatcher setup at all.

Rule: unbounded for intents, bounded for effects, keyed cancellation for per-entity async work.

Testing pyramid, briefly

Tier	Framework	Why MVI matters
Reducer	JUnit 4 + plain assertions	Pure function. No `runTest`, no `Dispatchers.setMain`, no mocks. ~5 ms/test. 80% of presentation tests live here.
Middleware	JUnit 4 + MockK + Turbine + `runTest`	One middleware at a time; fake repository.
Store integration	JUnit 4 + Turbine + `runTest`	Real reducer + real middlewares + fake repo.
Screen	Compose testing + Hilt	Single `onIntent` capture list per test.
Macrobenchmark	Macrobenchmark	Cold startup, scroll, resume-from-background, intent-to-render.

Eighty percent of presentation tests live at the reducer tier — pure function, plain JUnit, no dispatcher setup, no mocks, no Robolectric. A reducer test runs in roughly five milliseconds; three reducer tests per intent (happy, error, edge) is the highest-leverage habit in the whole pyramid. Parameterised blocks fold repetitive Throwable -> UiText mappings into one runner. See https://medium.com/@ouday.khaled/pure-reducers-in-kotlin-why-your-android-unit-tests-should-run-in-5-milliseconds-a4277cea3c38 for the reducer patterns and https://medium.com/@ouday.khaled/the-android-testing-pyramid-that-strict-mvi-unlocks-2f3e7cb1aebc for the full breakdown:

Tier	Rough cost per test	What it catches	Coverage target
Reducer	~5 ms	State-transition correctness, edge cases, no-op guards.	95% branch coverage on the reducer object.
Middleware	~80 ms	Async orchestration, cancellation, error routing.	Every `process` branch, every Flow pipeline.
Store integration	~150 ms	Wiring regressions, middleware ordering, follow-up intents.	One test per cross-middleware interaction.
Screen	~400 ms	Rendering, accessibility, intent capture on gestures.	One test per meaningful state variant.
Macrobenchmark	seconds	Baseline profile journeys, resume-from-background, scroll.	Every interactive path a user can trigger.

Replay is the hidden payoff — reducers are pure, so an entire session is reproducible by folding an intent recording through the reducer:

val replayed = recording.fold(FactsState()) { s, intent ->
    FactsReducer.reduce(s, intent).state
}

An IntentRecorderMiddleware captures the intent stream into a bounded ring buffer flushed on crash. Guardrails keep this honest:

Record intents only, never effects — replaying effects re-triggers navigation and toasts.
Scrub PII from intent payloads (search queries, draft text) before persisting.
Use for QA bug reports; do not pipe recorded intents back into a live UI.
Version the Intent contract alongside the ring buffer so a rename does not silently invalidate every recording.

A starter test catalogue for a mid-sized feature, sized against a ten-intent contract:

Suite	Count	What each test asserts
Reducer happy paths	10	For every intent, a representative state before produces the expected state after.
Reducer error paths	10	`*Failed(cause)` intents produce the correct `ErrorPresentation` shape.
Reducer edge / no-op	10	Re-sending during loading or at page boundaries returns the same state reference.
Middleware async	5	Data middleware translates use-case output into `FactsReceived` / `FactsLoadFailed`.
Middleware cancellation	2	Rapid `ToggleBookmark(id)` pairs cancel the stale job via the keyed map.
Store integration	3	End-to-end search, refresh, and toggle exercise the whole pipeline.
Screen capture	4	Each meaningful variant renders; tapping a row dispatches the matching intent.
Macrobenchmark	2	Cold start plus the intent journey (refresh → search → toggle → navigate → retry).

Rule: pay for reducer tests first; the pyramid collapses when the base tier is thin.

DEV Community: Ouday khaled

Pure Reducers in Kotlin: Why Your Android Unit Tests Should Run in 5 Milliseconds

What a reducer is

No-op detection

Mutation composition

Why tests are 5ms

What belongs outside the reducer

Where to go next

The Android Testing Pyramid That Strict MVI Unlocks

Five tiers at a glance

Reducer tier — 80% of tests

Middleware tier with Turbine

Store integration tier

Screen and macrobenchmark

Coverage targets

Where to go next

10 MVI Anti-Patterns Senior Android Reviewers Reject on Sight

The ten

1. The God Intent

2. Fat State

3. Side-Effecting Reducer

4. Effect Used as Intent

5. Named Public Methods on the Store

6. State-in-Effect via Navigate*(snapshot)

7. SharedFlow for Effects

8. onEvent Wrapper Type

9. Middleware Mutating State Directly

10. Swallowed CancellationException

Review-meeting pocket guide

Where to go next

The Strict-MVI Playbook: How Staff Android Engineers Structure Jetpack Compose at Scale

The contract: three sealed types

The runtime: Store, Reducer, Middleware

Twelve non-negotiables

Directory layout

Compose: Route versus Screen

Flow and coroutines cheat sheet

Testing pyramid, briefly

Where to go next

6. State-in-Effect via `Navigate*(snapshot)`

7. `SharedFlow` for Effects

8. `onEvent` Wrapper Type

10. Swallowed `CancellationException`