Forem: Shiva Thapa

I Got Tired of Reverse-Engineering My Own Architecture. So I Built a Tool to See It.

Shiva Thapa — Sat, 21 Mar 2026 06:40:47 +0000

There's a moment that every developer on a growing Kotlin or Android project will recognize.

A new engineer joins the team. They want to understand how the system is structured before they write their first line of code. So they open the project. They see 30 modules. They ask: "Where should I start?"

And nobody has a good answer.

The architecture diagram on the wiki is from 18 months ago. The tech spec references modules that were renamed twice. The most honest answer is: "Just dig into the Gradle files and figure it out."

I've been on both sides of that conversation. And it bothered me enough that I decided to fix it.

The Problem Nobody Names Directly

When you're working on a 5-module project, architecture is obvious. Everything fits in your head.

Past 15–20 modules, something changes. The system becomes too large to hold in working memory. And because Gradle builds succeed even when your dependency graph is a mess, the degradation is silent. There's no compiler warning for "your data layer now depends on your presentation layer." No test failure for "two feature modules have secretly coupled to each other."

By the time someone notices - usually during a painful refactoring, a CI build time regression, or an attempt to extract a feature into a separate app - the technical debt has compounded for months.

The root cause is that the real architecture of a multi-module project lives inside the Gradle dependency graph, not in any diagram, doc, or spec.

What Already Exists (And Why It Wasn't Enough)

I looked at every tool in the Kotlin ecosystem before building anything.

Dependency Analysis Plugin by autonomousapps is excellent - but it focuses on unused dependencies and ABI surface. It tells you what you don't need. Not what your structure looks like.

Module Graph Assert by jraska generates Graphviz graphs and does have a CI enforcement layer - assertModuleGraph can fail the build using regex-based rules and max tree height checks. The gap is elsewhere: no interactive visualization, no historical tracking, and KMP support requires manually adding source set configuration because the plugin has no native awareness of KMP module boundaries.

ArchUnit is the closest thing to what I wanted. But it's Java-centric, has no visualization layer, and building meaningful tests against a Gradle project structure requires significant boilerplate that feels out of place in a Kotlin codebase.

None of them do all three things: visualize, enforce, and track. Not together, not in a single tool, not with KMP awareness. That gap is what Aalekh is designed to fill.

What Aalekh Does

Two lines to set up:

// settings.gradle.kts
plugins {
    id("io.github.shivathapaa.aalekh") version "0.1.0"
}

One command to run:

./gradlew aalekhReport

A self-contained HTML file opens in your browser. No server. No CDN. No internet connection required. The entire report - including the D3.js visualization engine and all your graph data - is embedded in a single file you can share over Slack or attach to a PR.

Want to see it before installing anything?

The interactive graph

Every module is a node. Every dependency is an edge. Node color tells you the module type at a glance - Android App is blue, KMP is purple, JVM Library is amber.

The useful part is what gets highlighted:

Circular dependency nodes pulse with a red ring
God modules (high fan-in AND fan-out) glow orange
The critical build path is traced in purple

You can filter edges by type, click any node to open the module inspector, and see fan-in, fan-out, instability index, and transitive dependency count per module.

Cycle detection that doesn't lie to you

One decision I spent real time on: test dependencies in cycle detection.

Consider this common pattern:

:core:datastore      → (nothing)
:core:datastore-test → :core:datastore (testImplementation)

Naive cycle detection flags this as a cycle. It isn't - it's a test fixtures module depending on the module it provides fixtures for.

Aalekh separates main-code cycles (real architectural errors, aalekhCheck fails on these) from test-only cycles (shown as info, never fail the build). This distinction means you can actually trust the violations you see.

Architecture metrics

The Metrics panel computes per-module numbers that turn subjective architectural conversations into objective data:

Metric	What it tells you
Fan-out	How many modules this module directly depends on
Fan-in	How many modules depend on this one
Instability	`fanOut / (fanIn + fanOut)` - 0 is stable, 1 is unstable
Transitive deps	Total modules reachable from this one
Critical path	Longest dependency chain - constrains build parallelism
God modules	High fan-in AND fan-out - hardest to change safely

These aren't vanity metrics. They're signals for where refactoring attention should go first.

CI enforcement

./gradlew aalekhCheck

Fails the build on violations. Automatically wired into ./gradlew check. Writes:

aalekh-results.xml - JUnit XML, works with every CI system natively
aalekh-results.json - full machine-readable report with graph, summary, violations, and metadata

GitHub Actions:

- name: Run architecture check
  run: ./gradlew aalekhCheck

- name: Upload Aalekh report
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: aalekh-report
    path: build/reports/aalekh/

How Aalekh Is Built Internally

I tried to apply the same principles to Aalekh's own structure that Aalekh helps you enforce in your project:

aalekh-model      ← Data classes only. Zero dependencies.
aalekh-analysis   ← Pure Kotlin. No Gradle API. Graph algorithms.
aalekh-report     ← Report generators. No Gradle API.
aalekh-gradle     ← Gradle API lives here and nowhere else.

The Gradle API only appears in the outermost module. Everything in aalekh-analysis and aalekh-report is pure Kotlin - fully unit-testable without Gradle on the classpath. The DFS cycle detection, topological sort, and instability computation all run in milliseconds in plain JUnit 5. Only the Gradle integration tests are slow.

Configuration cache compatibility

Gradle 9.x enables configuration cache by default. Task actions run in a separate JVM from project configuration - you cannot capture live Project, Configuration, or Dependency objects inside a task.

The solution: all dependency data is serialized to plain String maps during configuration (inside provider { } lambdas), passed as @Input primitives to AalekhExtractTask, which writes graph.json. Report and check tasks read from that file. No live Gradle objects survive into any task action.

Configuration phase:
  provider { buildSubprojectData(rootProject) }  ← runs at config time
  → Map<String, List<String>>                    ← plain strings, CC-safe

Execution phase:
  AalekhExtractTask  → writes graph.json
  AalekhReportTask   → reads graph.json → writes index.html
  AalekhCheckTask    → reads graph.json → writes results.xml + results.json

The intermediate graph.json is also what makes the tool extensible - anyone can build additional tooling on top of it without touching the plugin.

What's Coming in v0.2.0

The current release covers visualization and cycle enforcement. Next up: layer enforcement via a Kotlin DSL - the thing I originally built this for.

aalekh {
    layers {
        layer("domain") {
            modules(":core:domain", ":feature:*:domain")
        }
        layer("data") {
            modules(":core:data", ":feature:*:data")
            canOnlyDependOn("domain")
        }
        layer("presentation") {
            modules(":feature:*:ui", ":app")
            canOnlyDependOn("domain", "data")
        }
    }

    featureIsolation {
        featurePattern = ":feature:**"
    }
}

When :feature:checkout:data adds implementation(project(":feature:checkout:ui")), the build fails with a message pointing to the exact file and line to fix.

Teams with existing violations can migrate gradually using severity overrides:

rules {
    rule("layer-dependency") {
        severity = Severity.WARNING  // see violations without blocking CI yet
    }
}

Promote to ERROR when you're ready to enforce.

Requirements

Gradle 9.0+

JVM 11+ (v0.1.1 fixes a crash that affected JDK 11–20)

Kotlin 2.3+

AGP 9.x+ (if Android)

Kotlin DSL only — settings.gradle.kts required (Groovy not supported)

Try It

// settings.gradle.kts
plugins {
    id("io.github.shivathapaa.aalekh") version "0.1.0"
}

./gradlew aalekhReport

shivathapaa / Aalekh

Aalekh is a Gradle plugin that extracts, visualizes, and enforces architectural rules across any Gradle multi-module project - Kotlin Multiplatform, Android, JVM, or any Gradle project.

Aalekh

Architecture Visualization & Linting for Gradle Multi-Module Projects

Aalekh is a Gradle plugin that extracts, visualizes, and enforces architectural rules across any Gradle multi-module project - Kotlin Multiplatform, Android, JVM, or any Gradle project. It gives teams three capabilities that no existing tool provides together: an interactive module graph, a Kotlin DSL for architecture rule enforcement, and historical metrics tracking.

Sample Reports

Now in Android App
- View locally
- View on GitHub Pages
Now in Android App - with cyclic dependency
- View locally
- View on GitHub Pages
Tallyo (KMP)
- View locally
- View on GitHub Pages

Sample Report Demo

Why Aalekh?

Tool	Visualizes	Enforces rules	Tracks metrics	KMP-aware
Aalekh	✓	✓	✓	✓

Aalekh visualizes, enforces, and tracks - in a single plugin, with zero external dependencies beyond the browser.

Quick Start

1. Add to settings.gradle.kts:

plugins {
    id("io.github.shivathapaa.aalekh") version "0.3.0"

…

View on GitHub

Free, open source (Apache 2.0), actively maintained. If you run it on your project and something breaks - or works better than expected - I'd genuinely like to know in the comments.

The next post will cover how the layer rule engine works under the hood - glob pattern resolution, violation message generation, and the severity migration system. Follow to get notified.

Pagination, WebSockets, and Coordinated Refresh in Kotlin Multiplatform

Shiva Thapa — Sun, 15 Mar 2026 15:53:29 +0000

Part 4 of 4 — The final part of this series. Parts 1, 2, and 3 cover the Ktor client setup, error-handling layer, and RequestState pattern that this part extends.

The first three parts built the foundation — a configured Ktor client, a typed error-handling layer, and a state management pattern that carries data cleanly from repository to UI. For a large class of screens, that's everything you need.

But some screens need more. A feed that loads pages of data as the user scrolls. A chat screen that receives real-time messages over a WebSocket connection while simultaneously loading paginated history. A screen that refreshes six independent data sources at once and needs to wait for all of them before hiding the pull-to-refresh indicator.

These aren't edge cases — they're common in any serious mobile app. And the good news is that none of them require new primitives. They all extend the same architecture you've already seen.

This part covers GenericPagingSource for pagination, PagingStateHandler for rendering every pagination state cleanly in the UI, WebSocketClientConnection and observeWebSocketMessages for real-time data, and RefreshManager for coordinated multi-source refreshes.

Pagination with `GenericPagingSource`

Writing a PagingSource for each paginated endpoint is repetitive. The structure is always the same: fetch a page, extract items from the response, determine the next page key, handle errors. The only things that change are the endpoint and the types.

GenericPagingSource eliminates that repetition entirely.

class GenericPagingSource<T : Any, R : Any>(
    private val fetchPage: suspend (Int) -> ResponseResult<R>,
    private val extractItems: (R) -> List<T>,
    private val getNextPageKey: (R) -> Int?,
    private val onError: (String, Int?, String?, ResponseResult.ErrorType?) -> Unit = { _, _, _, _ -> },
    private val onEmpty: () -> Unit = {}
) : PagingSource<Int, T>() {

    override fun getRefreshKey(state: PagingState<Int, T>): Int? {
        return state.anchorPosition?.let { anchorPosition ->
            state.closestPageToPosition(anchorPosition)?.prevKey?.plus(1)
                ?: state.closestPageToPosition(anchorPosition)?.nextKey?.minus(1)
        }
    }

    override suspend fun load(params: LoadParams<Int>): LoadResult<Int, T> {
        return try {
            val position = params.key ?: FIRST_PAGE_INDEX

            when (val result = fetchPage(position)) {
                is ResponseResult.Success -> {
                    val data = result.data
                        ?: return LoadResult.Error(Exception("Empty response"))
                    LoadResult.Page(
                        data = extractItems(data),
                        prevKey = if (position == FIRST_PAGE_INDEX) null else position - 1,
                        nextKey = getNextPageKey(data)
                    )
                }
                is ResponseResult.Empty -> {
                    onEmpty()
                    LoadResult.Page(data = emptyList(), prevKey = null, nextKey = null)
                }
                is ResponseResult.Error -> {
                    onError(result.message, result.code, result.serverMessage, result.errorType)
                    LoadResult.Error(Exception(result.message))
                }
            }
        } catch (e: Exception) {
            LoadResult.Error(e)
        }
    }

    companion object {
        private const val FIRST_PAGE_INDEX = 1
    }
}

Four parameters define the entire pagination behaviour for any endpoint:

fetchPage — a suspend function that takes a page number and returns a ResponseResult<R>. This is always a repository call. It returns ResponseResult — the same type every other repository function in this architecture returns. GenericPagingSource handles all three outcomes: success with data, empty response, and error.

extractItems — given the full response type R, pull out the List<T> of actual items. This handles the typical API envelope pattern where your response carries { results: [...], nextPage: 2 }.

getNextPageKey — return the next page number, or null when you've reached the last page.

onError / onEmpty — optional callbacks for side effects, like showing a snackbar or updating a separate piece of UI state.

Using It in a ViewModel

A paginated list with type filtering, in about fifteen lines:

fun fetchItemsByType(type: String?): Flow<PagingData<ItemDetails>> {
    return Pager(
        config = PagingConfig(
            pageSize = 10,
            prefetchDistance = 1,
            enablePlaceholders = false
        ),
        pagingSourceFactory = {
            GenericPagingSource(
                fetchPage = { page ->
                    repository.fetchPaginatedItems(page = page, pageSize = 10, type = type)
                },
                extractItems = { it.details },
                getNextPageKey = { it.nextPage }
            )
        }
    ).flow.cachedIn(viewModelScope)
}

cachedIn(viewModelScope) is important. Without it, the PagingData flow recreates from scratch on every subscription — including on recomposition. For a content-heavy feed where the user scrolls quickly, tune prefetchDistance accordingly:

val feedItems: Flow<PagingData<FeedItem>> = Pager(
    config = PagingConfig(
        pageSize = 10,
        prefetchDistance = 5,  // start loading next page when 5 items from the end
        enablePlaceholders = false
    ),
    pagingSourceFactory = {
        GenericPagingSource(
            fetchPage = { page ->
                feedRepository.fetchFeed(page = page, pageSize = 10)
            },
            extractItems = { it.results },
            getNextPageKey = { it.nextPage }
        )
    }
).flow.cachedIn(viewModelScope)

Pagination That Also Updates Other State

The fetchPage lambda is just a suspend function — there's nothing stopping you from doing more inside it. Consider a chat screen where the first page response also carries metadata about the conversation:

val messages: Flow<PagingData<ChatMessage>> = Pager(
    config = PagingConfig(pageSize = 10, prefetchDistance = 5, enablePlaceholders = false),
    pagingSourceFactory = {
        GenericPagingSource(
            fetchPage = { page ->
                val response = chatRepository.fetchMessages(chatId = chatId, page = page)

                // On first page only — extract metadata and bootstrap dependent state
                if (response.isSuccess && _uiState.value.chatMeta.isOwnChat == null) {
                    val body = response.getOrNull()
                    _uiState.update {
                        it.copy(
                            chatMeta = ChatMeta(
                                isOwnChat = body?.isOwnChat,
                                isFeedbackPending = body?.isFeedbackPending,
                                isClosed = body?.isClosed
                            )
                        )
                    }
                    if (body?.isOwnChat == true && body.isFeedbackPending == true) {
                        fetchFeedbackOptions()
                    }
                    initializeSocketConnection()
                }
                response
            },
            extractItems = { it.results ?: emptyList() },
            getNextPageKey = { it.nextPage }
        )
    }
).flow.cachedIn(viewModelScope)

The guard _uiState.value.chatMeta.isOwnChat == null ensures bootstrapping runs exactly once — on the first page load, not on every subsequent page or refresh. This is a production pattern worth internalising: pagination and dependent state initialisation co-located where they belong, without tangling the ViewModel's init block with timing dependencies.

Rendering Pagination State with `PagingStateHandler`

GenericPagingSource takes care of fetching pages. But the Paging library produces more than just data — it produces load states. There's an initial load, an append load as the user scrolls, a prepend load for reverse-layout lists, a refresh triggered by pull-to-refresh, and error states for each. Each one needs a corresponding UI.

PagingStateHandler encapsulates all of that.

@Composable
fun <T : Any> PagingStateHandler(
    lazyPagingItems: LazyPagingItems<T>,
    modifier: Modifier = Modifier,
    initialLoadingContent: @Composable (Modifier) -> Unit = { DefaultLoading(it) },
    refreshLoadingContent: @Composable (Modifier) -> Unit = initialLoadingContent,
    appendLoadingContent:  @Composable (Modifier) -> Unit = refreshLoadingContent,
    prependLoadingContent: @Composable (Modifier) -> Unit = appendLoadingContent,
    initialErrorContent:   @Composable BoxScope.(Modifier, Throwable, () -> Unit) -> Unit = { mod, error, retry ->
        DefaultInitialError(mod, error, retry)
    },
    appendErrorContent:    @Composable ColumnScope.(Modifier, Throwable, () -> Unit) -> Unit = { mod, error, retry ->
        DefaultAppendError(mod, error, retry)
    },
    prependErrorContent:   @Composable ColumnScope.(Modifier, Throwable, () -> Unit) -> Unit = { mod, error, retry ->
        DefaultPrependError(mod, error, retry)
    },
    emptyContent:          @Composable BoxScope.(Modifier) -> Unit = { DefaultEmptyContent(it) },
    fullyLoadedContent:    @Composable ColumnScope.(Modifier) -> Unit = { },
    showFullyLoaded: Boolean = true,
    content: @Composable (LazyPagingItems<T>) -> Unit
) {
    val loadState = lazyPagingItems.loadState

    val isInitialLoading = loadState.refresh is LoadState.Loading
    val isInitialError   = loadState.refresh is LoadState.Error
    val isEmpty          = loadState.refresh is LoadState.NotLoading && lazyPagingItems.itemCount == 0
    val isFullyLoaded    = loadState.append.endOfPaginationReached && !isInitialLoading && lazyPagingItems.itemCount > 0

    Box(modifier = modifier) {
        when {
            isInitialError -> {
                val error = (loadState.refresh as LoadState.Error).error
                initialErrorContent(Modifier.fillMaxSize(), error) { lazyPagingItems.retry() }
            }
            isEmpty -> {
                emptyContent(Modifier.fillMaxSize())
            }
            isInitialLoading -> {
                initialLoadingContent(Modifier.fillMaxSize())
            }
            else -> {
                Column(modifier = Modifier.fillMaxSize()) {
                    when (loadState.prepend) {
                        is LoadState.Loading -> prependLoadingContent(Modifier.fillMaxWidth())
                        is LoadState.Error -> {
                            val error = (loadState.prepend as LoadState.Error).error
                            prependErrorContent(Modifier.fillMaxWidth(), error) { lazyPagingItems.retry() }
                        }
                        else -> {}
                    }

                    Box(modifier = Modifier.weight(1f)) { content(lazyPagingItems) }

                    when {
                        loadState.append is LoadState.Loading ->
                            appendLoadingContent(Modifier.fillMaxWidth())
                        loadState.append is LoadState.Error -> {
                            val error = (loadState.append as LoadState.Error).error
                            appendErrorContent(Modifier.fillMaxWidth(), error) { lazyPagingItems.retry() }
                        }
                        isFullyLoaded && showFullyLoaded ->
                            fullyLoadedContent(Modifier.fillMaxWidth())
                    }
                }
            }
        }

        // Refresh overlay — shown when pull-to-refresh fires while items are already visible
        if (loadState.refresh is LoadState.Loading && !isInitialLoading) {
            refreshLoadingContent(Modifier.align(Alignment.TopCenter))
        }
    }
}

The State Machine

Five scenarios, resolved in priority order:

Initial error — the very first load failed. The entire content area is replaced with an error UI and a retry button
Empty — first load succeeded but returned nothing. Shows an empty placeholder. This is a successful state, not an error — the distinction matters for the message you show the user
Initial loading — first load in progress. Shows a full-area shimmer or skeleton
Active — normal operating state. A Column manages prepend loading/error at the top, the content lambda in the middle, and append loading/error/fully-loaded at the bottom
Refresh overlay — pull-to-refresh while items are visible. A lightweight indicator overlaid at the top, not replacing the existing content

The `content` Lambda Pattern

In practice the content lambda is almost always left empty:

item("PagingFooter") {
    PagingStateHandler(
        lazyPagingItems = feedItems,
        initialLoadingContent = { FeedLoadingSkeleton(count = 10) },
        refreshLoadingContent = { FeedLoadingSkeleton(count = 2) },
        emptyContent = {
            EmptyPlaceholder(
                message = stringResource(Res.string.no_items_found),
                icon = painterResource(Res.drawable.empty_icon)
            )
        },
        modifier = Modifier.fillMaxWidth().animateItem(),
        content = { /* items rendered in the LazyColumn above */ }
    )
}

PagingStateHandler is placed as a single item after all the real list items in the LazyColumn. The actual items are rendered in the items { } block above it — as usual. PagingStateHandler handles only state UI: the shimmer on first load, the error view, the empty placeholder, the append spinner.

Per-Screen Customisation

Every parameter except lazyPagingItems has a default. Override only what's different:

// Card-based list — custom skeletons, no "all loaded" footer
PagingStateHandler(
    lazyPagingItems = items,
    initialLoadingContent = { CardListSkeleton(cardHeight = 132.dp, count = 12) },
    appendLoadingContent  = { mod -> CardListSkeleton(modifier = mod, count = 2) },
    refreshLoadingContent = { CardListSkeleton() },
    emptyContent          = { EmptyState(modifier = Modifier.padding(top = 84.dp)) },
    showFullyLoaded = false,
    modifier = Modifier.fillMaxWidth().animateItem(),
    content = { /* items rendered above */ }
)

// Chat screen — message skeletons, prepend handled for reverse layout
item("ChatPagingFooter") {
    PagingStateHandler(
        lazyPagingItems = chatMessages,
        initialLoadingContent = { MessageSkeleton(count = 7) },
        refreshLoadingContent = { MessageSkeleton(count = 3) },
        modifier = Modifier.fillMaxWidth().animateItem(),
        content = { /* messages rendered above */ }
    )
}

This is the same principle as displayResultWithDefaults from Part 3 — convention over configuration, with full override capability.

Real-Time Data with WebSockets

`WebSocketClientConnection`

WebSocketClientConnection is a self-contained WebSocket manager. You give it a URL and a coroutine scope, and it handles the rest — connection establishment, message routing, ping/pong, reconnection on failure, and clean shutdown.

class WebSocketClientConnection(
    private val socketUrl: String,
    private val autoReconnect: Boolean = true,
    private val scope: CoroutineScope,
    // ...
) {
    private val _connectionState = MutableStateFlow<ConnectionState>(ConnectionState.Disconnected)
    val connectionState: StateFlow<ConnectionState> = _connectionState.asStateFlow()

    private val _messages = MutableSharedFlow<String>()
    val messages: SharedFlow<String> = _messages.asSharedFlow()

    private val outgoingMessages = Channel<String>(Channel.BUFFERED)

    sealed class ConnectionState {
        data object Disconnected : ConnectionState()
        data object Connecting   : ConnectionState()
        data object Connected    : ConnectionState()
        data class  Error(val error: Exception) : ConnectionState()
    }
}

The public surface is small by design: two observable flows (connectionState, messages), one method for sending (sendMessage), one for shutdown (disconnect). All the complexity — mutex-protected session, separate coroutines for incoming and outgoing processing, exponential backoff reconnection — stays internal.

Connection and Reconnection

fun connect() {
    if (_connectionState.value is ConnectionState.Connected ||
        _connectionState.value is ConnectionState.Connecting) return

    reconnectJob = scope.launch {
        var retryCount = 0
        var retryDelay = INITIAL_RETRY_DELAY_MS  // 1000ms

        while (isActive) {
            try {
                _connectionState.value = ConnectionState.Connecting

                httpClient.webSocket(urlString = socketUrl, request = {
                    headers {
                        append("Authorization", userRepository.userTokenData.value?.accessToken ?: "")
                        append("Accept-Language", appLocalizationRepository.languagePreference.value.serverCode)
                    }
                }) {
                    sessionMutex.withLock { session = this }
                    _connectionState.value = ConnectionState.Connected
                    retryCount = 0
                    retryDelay = INITIAL_RETRY_DELAY_MS

                    startMessageProcessing()

                    suspendCancellableCoroutine<Unit> { continuation ->
                        continuation.invokeOnCancellation { scope.launch { cleanup() } }
                    }
                }
            } catch (e: IOException) {
                handleConnectionError(e, retryCount, retryDelay)
                if (!shouldRetryConnection(retryCount)) break
                retryCount++
                retryDelay = (retryDelay * BACKOFF_MULTIPLIER).toLong().coerceAtMost(MAX_RETRY_DELAY_MS)
                delay(retryDelay.milliseconds)
            } catch (e: Exception) {
                handleConnectionError(e, retryCount, retryDelay)
                break  // Non-IO exceptions are not retried
            }
        }
    }
}

Key design decisions:

suspendCancellableCoroutine keeps the coroutine and the session alive without busy-waiting. The actual work happens in startMessageProcessing(), which launches two child coroutines — one for incoming, one for outgoing
IOException is retried; other exceptions are not. Network errors are transient. Programming errors, protocol violations, and coroutine cancellations are not. This prevents the reconnection loop from spinning on non-recoverable errors
Exponential backoff is capped — 1s → 5s max, stops after 5 consecutive failures
The auth token is read at connection time, not construction time — same principle as defaultRequest in the HTTP client

Incoming Message Processing

private suspend fun processIncomingMessages(session: DefaultClientWebSocketSession) {
    try {
        for (frame in session.incoming) {
            when (frame) {
                is Frame.Text  -> _messages.emit(frame.readText())
                is Frame.Close -> break
                is Frame.Ping  -> if (session.isActive) session.send(Frame.Pong(frame.data))
                else           -> { /* ignore binary frames */ }
            }
        }
    } catch (e: EOFException) {
        if (autoReconnect && scope.isActive) handleMessageProcessingError(e)
    } catch (e: CancellationException) {
        // Normal shutdown — do nothing
    } catch (e: Exception) {
        if (autoReconnect && scope.isActive) handleMessageProcessingError(e)
    } finally {
        cleanup()
    }
}

Ping/pong is handled manually in addition to the plugin-level pingInterval. Responding to server-initiated pings keeps the connection alive from the server's perspective, while pingInterval handles client-initiated keepalives. Both together mean the connection survives aggressive network management on Android and iOS.

`observeWebSocketMessages` — Decoding and Routing in One Call

Note: The message routing here is specific to a backend envelope format with type and data fields. Your backend may use a different shape — only the envelope parsing would need to change.

inline fun <reified T : Any?> observeWebSocketMessages(
    client: WebSocketClientConnection?,
    scope: CoroutineScope,
    crossinline onMessage: (T?) -> Unit,
    crossinline onProcessing: (T?) -> Unit = {},
    crossinline onError: (Throwable) -> Unit = {},
    crossinline onConnectionStateChanged: (WebSocketClientConnection.ConnectionState) -> Unit = {}
) {
    if (client == null) return

    val json = JsonConfig.parser

    scope.launch {
        client.messages.collect { rawMessage ->
            try {
                val envelope = json.decodeFromString<DefaultResponseDto<JsonElement>>(rawMessage)

                when (envelope.type) {
                    SocketResponseType.DATA.key -> {
                        envelope.data?.let { payload ->
                            onMessage(json.decodeFromJsonElement<T>(payload))
                        }
                    }
                    SocketResponseType.PROCESSING.key -> {
                        envelope.data?.let { payload ->
                            onProcessing(json.decodeFromJsonElement<T>(payload))
                        }
                    }
                    else -> onProcessing(null)
                }
            } catch (e: Exception) {
                onProcessing(null)
                onError(e)
            }
        }
    }

    scope.launch {
        client.connectionState.collect { state -> onConnectionStateChanged(state) }
    }

    client.connect()
}

The function is reified so it decodes the JSON payload into T without a class reference. The two-stage decode — first into DefaultResponseDto<JsonElement>, then from JsonElement into T — handles the envelope pattern: the outer wrapper carries a type field, and the inner data is the actual payload.

The function also calls client.connect(). Observing the messages is the signal to connect — no separate connect call needed. It's idempotent: connect() returns early if a connection is already in progress.

Using It in a ViewModel

private fun initializeSocketConnection() {
    if (uiState.value.chatMeta.isOwnChat != true) return

    webSocketClient = chatRepository.createWebSocketConnection(
        chatId = chatId,
        scope = viewModelScope
    )

    observeWebSocketMessages<ChatMessageDto?>(
        client = webSocketClient,
        scope = viewModelScope,
        onMessage    = { dto -> dto?.toDomain()?.let { appendMessageFromSocket(it) } },
        onProcessing = { dto -> updateProcessingIndicator(dto?.toDomain()) },
        onError      = { error -> Logger.debug("WebSocket error: ${error.message}") },
        onConnectionStateChanged = { state -> Logger.debug("WebSocket state: $state") }
    )
}

override fun onCleared() {
    super.onCleared()
    webSocketClient?.disconnect()
}

The scope cancellation from onCleared() automatically stops the collecting coroutines, but disconnect() sends a proper WebSocket close frame to the server. Without it, the server may not know the client left and keeps the session allocated.

The repository side stays minimal:

override fun createWebSocketConnection(chatId: Int, scope: CoroutineScope): WebSocketClientConnection {
    val url = "${WSS_URL}ws/chat/$chatId/"
    return WebSocketClientConnection(socketUrl = url, scope = scope)
}

Coordinated Refresh with `RefreshManager`

typealias RefreshManagerFactory = (
    scope: CoroutineScope,
    onStart: () -> Unit,
    onEnd: () -> Unit
) -> RefreshManager

class RefreshManager(
    private val coroutineScope: CoroutineScope,
    private val minDurationMillis: Long = 1500L,
    private val onRefreshStart: () -> Unit,
    private val onRefreshEnd: () -> Unit
) {
    private val jobs = mutableListOf<Job>()

    @Volatile
    private var isRefreshing = false

    fun add(jobProvider: () -> Job) { jobs.add(jobProvider()) }

    fun addSuspending(block: suspend () -> Unit) {
        jobs.add(coroutineScope.launch {
            try { block() }
            catch (e: Exception) { Logger.error("Error in refresh block: ${e.message}") }
        })
    }

    fun start() {
        if (isRefreshing) return
        isRefreshing = true

        coroutineScope.launch {
            onRefreshStart()
            try {
                val delayJob = launch { delay(minDurationMillis) }
                jobs.add(delayJob)
                jobs.joinAll()
            } finally {
                onRefreshEnd()
                jobs.clear()
                isRefreshing = false
            }
        }
    }
}

Register jobs with add() or addSuspending(). Call start(). RefreshManager fires onRefreshStart(), launches all jobs concurrently alongside a minimum-duration delay, waits for all of them to finish, then fires onRefreshEnd().

The minDurationMillis of 1500ms prevents the jarring flash of a spinner that appears and disappears in 200ms. If all API calls complete in 400ms, the refresh indicator still shows for the full 1.5 seconds.

fun refreshAllData() {
    val refreshManager = refreshManagerFactory(
        viewModelScope,
        onStart = { _uiState.update { it.copy(isRefreshing = true) } },
        onEnd   = { _uiState.update { it.copy(isRefreshing = false) } }
    )

    viewModelScope.launch {
        refreshManager.add { fetchWeatherData() }
        refreshManager.add { fetchTaskReminders() }
        refreshManager.add { fetchNotificationCount() }
        refreshManager.add { fetchBanners() }
        refreshManager.add { fetchMarketPrices() }
        refreshManager.addSuspending { resetInputState() }
        refreshManager.start()
    }
}

refreshManagerFactory is a typealias rather than a direct constructor call. In tests, you swap the factory for a synchronous or mock implementation without coroutine timing concerns. The typealias keeps injection clean without needing a full interface.

Pagination + WebSockets: How They Coexist on the Same Screen

The real payoff of this architecture is how naturally these pieces compose. A chat screen combining paginated history with live incoming messages is a common requirement — here's how both data paths coexist without interfering.

Paginated history flows through GenericPagingSource as LazyPagingItems. New socket messages are stored in a separate socketMessages list in UiState. The typing indicator lives in its own processingMessage field. The two paths update independent state fields:

private fun appendMessageFromSocket(message: ChatMessage) {
    _uiState.update { state ->
        val updated = state.socketMessages.toMutableList()
        updated.add(0, message)  // prepend for reversed layout
        state.copy(socketMessages = updated)
    }
}

private fun updateProcessingIndicator(message: ChatMessage?) {
    _uiState.update { state -> state.copy(processingMessage = message) }
}

A single LazyColumn renders four sections in order:

LazyColumn(reverseLayout = isOwnChat) {

    // 1. Typing indicator — from WebSocket processing state
    item {
        AnimatedVisibility(visible = processingMessage?.isTyping == true) {
            TypingIndicator()
        }
    }

    // 2. Real-time messages — arrived via WebSocket, not yet in pagination
    if (socketMessages.isNotEmpty()) {
        itemsIndexed(
            items = socketMessages,
            key = { index, msg -> "${msg.id}-socket-$index" }
        ) { _, message ->
            MessageBubble(message = message)
        }
    }

    // 3. Historical messages — loaded via pagination
    items(
        count = chatMessages.itemCount,
        key = { index -> chatMessages.peek(index)?.id ?: index }
    ) { index ->
        chatMessages[index]?.let { MessageBubble(message = it) }
    }

    // 4. Pagination state — initial loading, append, empty, errors
    item("ChatPagingFooter") {
        PagingStateHandler(
            lazyPagingItems = chatMessages,
            initialLoadingContent = { MessageSkeleton(count = 7) },
            refreshLoadingContent = { MessageSkeleton(count = 3) }
        )
    }
}

With reverseLayout = true, new socket messages prepended to the front appear at the bottom. Historical paged messages appear above as the user scrolls up. The typing indicator sits at the bottom above the newest message.

The two data sources are completely independent. If the socket drops and reconnects, the paginated history is unaffected. If the user scrolls back through history, new messages keep arriving at the bottom. The paths don't interfere because they never share the same data structure.

Putting It All Together

Looking back across all four parts, here's the complete architecture:

A single, consistently configured HttpClient — auth, token refresh, retries, timeouts, and logging declared once, injected everywhere as a singleton.

A complete error-handling boundary at safeRequest — every failure mode Ktor can produce is caught, classified, and returned as a typed ResponseResult with user-facing messages and error type enums.

A UI state machine in RequestState — the full lifecycle of any request (idle, loading, success, error, empty) flows through executeNetworkCall and executeNetworkCallWithState into UiState, and renders through displayResult and displayResultWithDefaults with animated transitions.

Infrastructure for the hard cases — GenericPagingSource for paginated lists with no boilerplate per endpoint, PagingStateHandler for rendering every load state with per-screen customisable defaults, WebSocketClientConnection for self-healing real-time connections, observeWebSocketMessages for typed message decoding and routing, and RefreshManager for coordinated multi-source refresh with minimum display duration.

Every screen follows the same pattern. The repository makes a typed call. The ViewModel runs it through executeNetworkCall or executeNetworkCallWithState. The UI observes a StateFlow<UiState> and renders through displayResult or PagingStateHandler. No special-casing for loading states, no inconsistent error handling, no try-catch scattered across ViewModel functions.

When a new feature needs to be added, the developer writes a repository function that returns ResponseResult<T>, wires it through executeNetworkCallWithState, stores the result in a RequestState field in UiState, and renders it with displayResultWithDefaults. The path is always the same. The only new code is the code that's actually unique to the feature.

That's the real value of this architecture — not any single clever piece, but the consistency it creates across a codebase that will grow, be maintained by different developers, and need to absorb new requirements over time.

Thanks for reading the full series. If you found it useful, sharing it with your team or leaving a comment goes a long way. All feedback welcome.

From Data to UI with RequestState in Kotlin Multiplatform

Shiva Thapa — Sun, 15 Mar 2026 15:52:13 +0000

Part 3 of 4 — This part builds on the ResponseResult contract from Part 2 and the HttpClient setup from Part 1. If you're jumping in here, those two parts cover the layers this one sits on top of.

In Part 2, we built a networking layer where every call returns a ResponseResult<T>. The repository knows nothing about loading state, error dialogs, or UI updates — it just makes the call and returns a typed result. Clean, testable, consistent.

But the ViewModel still has to react to those results. It needs to set loading to true before the call, update state when it succeeds, show an error when it fails, and set loading to false when it's done. Across a real app with dozens of screens, this ceremony adds up fast. And if every developer handles it slightly differently, you end up with the same inconsistency problem you had in the repository layer — just one floor higher.

This part solves that. We'll build RequestState — the UI-side equivalent of ResponseResult — and wire it to executeNetworkCall and executeNetworkCallWithState, which handle the entire loading/success/error lifecycle in a single call. Finally, we'll look at the Compose extensions that let your UI react to state changes in a single, animated, readable block.

The Gap Between Repository and UI

When a ViewModel calls a repository function, it gets a ResponseResult<T>. But the UI doesn't just need to know whether the data arrived — it needs to know where in the journey it is. Before the call starts, nothing has happened yet. During the call, something is loading. When it completes, data is available. When it fails, an error needs to be shown. When the server responds with nothing, an empty state needs to be rendered.

ResponseResult models the outcome of a call. What we need for the UI is something that models the state over time. That's RequestState.

`RequestState` — UI State That Tells the Whole Story

sealed class RequestState<out T> {
    data object Idle    : RequestState<Nothing>()
    data object Loading : RequestState<Nothing>()
    data class  Success<out T>(val data: T) : RequestState<T>()
    data class  Error(
        val message: String,
        val code: Int? = null,
        val serverMessage: String? = null,
        val errorType: ResponseResult.ErrorType? = null
    ) : RequestState<Nothing>()
    data object Empty   : RequestState<Nothing>()
}

Five states. Each one corresponds to a real moment in the lifecycle of a network call.

Idle — the initial state before anything has been requested. A screen that hasn't loaded yet isn't in a loading state; it hasn't started. This distinction matters when you want to avoid flashing a loading indicator on first render, or when you need to show a "tap to load" placeholder.

Loading — a request is in flight.

Success<T> — the request succeeded. Notice that unlike ResponseResult.Success, the data here is non-nullable. By the time a success state reaches the UI, it should carry real data. If the server returned nothing, that's Empty, not Success(null).

Error — carries the same fields as ResponseResult.Error: a user-facing message, the status code, the server message, and the ErrorType enum for branching on failure kind.

Empty — the request succeeded but there's nothing to show. Your UI can render an empty placeholder without having to check Success(emptyList()).

Helper Functions

fun isIdle()    : Boolean = this is Idle
fun isLoading() : Boolean = this is Loading
fun isError()   : Boolean = this is Error
fun isSuccess() : Boolean = this is Success
fun isEmpty()   : Boolean = this is Empty

fun getSuccessData()       = (this as Success).data
fun getSuccessDataOrNull() = if (this is Success) this.data else null
fun getErrorMessage()      = (this as Error).message
fun getErrorMessageOrNull() = if (this is Error) this.message else null

isLoading() and isSuccess() are particularly useful in ViewModels when you need to guard against duplicate requests — for example, not starting a new fetch if one is already running.

Transformation

RequestState supports map and mapNotNull, which work just like their ResponseResult counterparts:

fun <T, R> RequestState<T>.map(transform: (T) -> R): RequestState<R> {
    return when (this) {
        is RequestState.Success -> RequestState.Success(transform(this.data))
        is RequestState.Error   -> this
        is RequestState.Loading -> RequestState.Loading
        is RequestState.Idle    -> RequestState.Idle
        is RequestState.Empty   -> RequestState.Empty
    }
}

fun <T, R> RequestState<T>.mapNotNull(transform: (T) -> R?): RequestState<R> {
    return when (this) {
        is RequestState.Success -> {
            val result = transform(this.data)
            if (result != null) RequestState.Success(result) else RequestState.Empty
        }
        is RequestState.Error   -> this
        is RequestState.Loading -> RequestState.Loading
        is RequestState.Idle    -> RequestState.Idle
        is RequestState.Empty   -> RequestState.Empty
    }
}

Non-success states pass through untouched. No pattern matching on every branch manually.

Inline Callbacks

inline fun <reified T> RequestState<T>.onSuccess(action: (T) -> Unit): RequestState<T> {
    if (this is RequestState.Success) action(data)
    return this
}

inline fun <reified T> RequestState<T>.onError(action: (String) -> Unit): RequestState<T> {
    if (this is RequestState.Error) action(message)
    return this
}

inline fun <reified T> RequestState<T>.onLoading(action: () -> Unit): RequestState<T> {
    if (this is RequestState.Loading) action()
    return this
}

inline fun <reified T> RequestState<T>.onEmpty(action: () -> Unit): RequestState<T> {
    if (this is RequestState.Empty) action()
    return this
}

These are chainable. You can write:

requestState
    .onSuccess { data -> renderContent(data) }
    .onError   { message -> showError(message) }
    .onEmpty   { showEmptyState() }

`handleResult` — For When You Need All Five Branches

fun <T> RequestState<T>.handleResult(
    onIdle:    (() -> Unit)? = null,
    onLoading: (() -> Unit)? = null,
    onError:   ((message: String, code: Int?, serverMessage: String?, errorType: ResponseResult.ErrorType?) -> Unit)? = null,
    onSuccess: (T) -> Unit,
    onEmpty:   (() -> Unit)? = null
) {
    when (this) {
        is RequestState.Idle    -> onIdle?.invoke()
        is RequestState.Loading -> onLoading?.invoke()
        is RequestState.Error   -> onError?.invoke(message, code, serverMessage, errorType)
        is RequestState.Success -> onSuccess(getSuccessData())
        is RequestState.Empty   -> onEmpty?.invoke()
    }
}

All callbacks except onSuccess are optional. This is used when multiple RequestState values drive different sections of the same scrollable screen — each section with its own loading skeleton, error state, and content:

uiState.weatherForecast.handleResult(
    onSuccess = { forecast ->
        item(key = "WeatherDetail") {
            WeatherDetailCard(forecast = forecast)
        }
    },
    onError = { _, _, serverMessage, _ ->
        item(key = "WeatherError") {
            NetworkErrorCard(
                onRetry = { viewModel.retryWeatherFetch() },
                errorMessage = serverMessage ?: stringResource(Res.string.could_not_load_weather)
            )
        }
    },
    onLoading = {
        item(key = "WeatherLoading") {
            WeatherLoadingSkeleton()
        }
    }
)

No when expressions scattered across the screen. No if (isLoading) show else hide logic. The pattern is the same every time.

`executeNetworkCall` — Wiring the Repository to the ViewModel

suspend inline fun <T : Any> executeNetworkCall(
    crossinline call: suspend () -> ResponseResult<T>,
    crossinline onLoadingChanged: (Boolean) -> Unit = {},
    crossinline onSuccess: (T) -> Unit,
    crossinline onError: (message: String, code: Int?, serverMessage: String?, errorType: ResponseResult.ErrorType?) -> Unit,
    crossinline onEmpty: () -> Unit = {}
) {
    onLoadingChanged(true)

    when (val result = call()) {
        is ResponseResult.Success -> {
            onLoadingChanged(false)
            result.data?.let(onSuccess) ?: onEmpty()
        }
        is ResponseResult.Error -> {
            onLoadingChanged(false)
            onError(result.message, result.code, result.serverMessage, result.errorType)
        }
        is ResponseResult.Empty -> {
            onLoadingChanged(false)
            onEmpty()
        }
    }
}

This function takes a suspended call that returns a ResponseResult, fires the loading callback when the call starts, and routes the result to the appropriate callback when it completes. The loading flag is always reset — in every branch, before the relevant callback fires — regardless of how the call ends.

A simple ViewModel function using it:

fun fetchBanners(): Job {
    return viewModelScope.launch {
        executeNetworkCall(
            call = { homeRepository.fetchBanners() },
            onSuccess = { banners -> _bannerList.value = banners },
            onError = { message, _, serverMessage, _ ->
                // handle silently or show a snackbar
            }
        )
    }
}

Three lines of intent: what to call, what to do on success, what to do on error. No try-catch. No manual loading flag management. No finally block.

For calls with visible loading state or file upload progress:

fun submitQuery() {
    viewModelScope.launch {
        executeNetworkCall(
            call = {
                repository.submitQuery(
                    payload = uiState.value.userQuery,
                    onProgress = { sent, total, _ ->
                        updateUploadStatus(UploadStatus(sent, total))
                    }
                )
            },
            onLoadingChanged = { isLoading ->
                _uiState.update { it.copy(isSending = isLoading) }
            },
            onSuccess = { response ->
                resetUserQuery()
                _uiEvents.tryEmit(UiEvent.NavigateToChat(response.id))
            },
            onError = { message, _, serverMessage, _ ->
                dialogStateHolder.showError(serverMessage ?: message)
            }
        )
    }
}

`executeNetworkCallWithState` — When the State Itself Lives in the ViewModel

executeNetworkCall is for fire-and-update patterns. But sometimes you want the RequestState itself stored in UiState, so the UI can react to every transition — idle, loading, success, error, empty — directly.

suspend inline fun <T : Any> executeNetworkCallWithState(
    crossinline call: suspend () -> ResponseResult<T>,
    crossinline onAllEvents: (RequestState<T>) -> Unit = {},
    crossinline onLoadingChanged: (Boolean) -> Unit = {},
    crossinline onSuccess: (T) -> Unit = {},
    crossinline onError: (message: String, code: Int?, serverMessage: String?, errorType: ResponseResult.ErrorType?) -> RequestState<T> = {
            message, code, serverMessage, errorType ->
        RequestState.Error(message = message, code = code, serverMessage = serverMessage, errorType = errorType)
    },
    crossinline onEmpty: () -> RequestState<T> = { RequestState.Empty }
): RequestState<T> {
    return try {
        onLoadingChanged(true)
        onAllEvents(RequestState.Loading)

        when (val result = call()) {
            is ResponseResult.Success -> {
                result.data?.let { data ->
                    val successState = RequestState.Success(data)
                    onAllEvents(successState)
                    onSuccess(data)
                    successState
                } ?: run {
                    onAllEvents(RequestState.Empty)
                    RequestState.Empty
                }
            }
            is ResponseResult.Error -> {
                val errorState = RequestState.Error(
                    message = result.message,
                    code = result.code,
                    serverMessage = result.serverMessage,
                    errorType = result.errorType
                )
                onAllEvents(errorState)
                onError(result.message, result.code, result.serverMessage, result.errorType)
                errorState
            }
            is ResponseResult.Empty -> {
                onAllEvents(RequestState.Empty)
                onEmpty()
                RequestState.Empty
            }
        }
    } catch (e: Exception) {
        val errorState = RequestState.Error(
            message = e.message ?: "An unknown error occurred",
            errorType = if (e.message.isNullOrBlank()) ResponseResult.ErrorType.UNKNOWN else null
        )
        onAllEvents(errorState)
        errorState
    } finally {
        onLoadingChanged(false)
    }
}

The key difference is onAllEvents. This single callback receives every state transition — Loading, Success, Error, Empty — making it trivial to pipe all transitions into one ViewModel field:

fun fetchWeatherForecast(lat: Double, lon: Double) {
    viewModelScope.launch {
        executeNetworkCallWithState(
            call = { weatherRepository.getDailyForecast(lat, lon) },
            onAllEvents = { state ->
                _uiState.update { it.copy(weatherForecast = state) }
            }
        )
    }
}

One line in onAllEvents. Loading state, success data, and any error all flow into the same UiState field. No separate isLoading boolean. No separate error string. The state machine is the state.

When you need extra logic on success — updating a cache, auto-selecting an item — onSuccess is there as an opt-in side channel alongside onAllEvents:

fun fetchNotificationCategories() {
    viewModelScope.launch {
        executeNetworkCallWithState(
            call = { notificationRepository.fetchCategories() },
            onSuccess = { categories ->
                // Auto-select the first category if none is selected yet
                if (uiState.value.selectedCategory == null) {
                    updateSelectedCategory(categories.firstOrNull(), index = null)
                }
            },
            onAllEvents = { state ->
                _uiState.update { it.copy(categories = state) }
            }
        )
    }
}

Both callbacks fire independently — they're not mutually exclusive.

The `UiState` Pattern

RequestState pairs naturally with a data class UiState exposed as a StateFlow:

data class UiState(
    val weatherForecast:     RequestState<List<DailyForecast>?> = RequestState.Idle,
    val marketPrices:        RequestState<List<MarketPrice>>    = RequestState.Idle,
    val notificationCount:   NotificationCount                  = NotificationCount(),
    val isRefreshing:        Boolean                            = false,
    // ...
)

private val _uiState = MutableStateFlow(UiState())
val uiState: StateFlow<UiState> = _uiState.asStateFlow()

Every RequestState field starts as Idle. As the ViewModel fires its initial requests in init, those fields transition through Loading to Success, Error, or Empty. The UI observes the StateFlow and renders whatever state it currently holds.

The ViewModel no longer needs three separate flags (isLoading, hasError, data) per network request. The entire lifecycle lives in one field, in one value, in one state machine.

Bringing It to the UI — `displayResult` and `displayResultWithDefaults`

Two Composable extension functions on RequestState<T> handle rendering.

`displayResult` — Full Control

@Composable
fun <T> RequestState<T>.displayResult(
    onSuccess: @Composable (T) -> Unit,
    modifier: Modifier = Modifier,
    parentModifier: Modifier = Modifier,
    onLoading: (@Composable () -> Unit)? = null,
    onIdle:    (@Composable () -> Unit)? = onLoading,
    onError:   (@Composable (String, Int?, String?, ResponseResult.ErrorType?) -> Unit)? = null,
    onEmpty:   (@Composable () -> Unit)? = null,
    transitionSpec: ContentTransform =
        fadeIn(tween(800)) togetherWith fadeOut(tween(800)),
    backgroundColor: Color? = null,
    contentAlignment: Alignment = Alignment.Center
) {
    AnimatedContent(
        modifier = parentModifier.background(color = backgroundColor ?: Color.Unspecified),
        targetState = this,
        transitionSpec = { transitionSpec },
        label = "ContentAnimation"
    ) { state ->
        Box(
            modifier = modifier.fillMaxWidth()
                .background(color = backgroundColor ?: Color.Unspecified),
            contentAlignment = contentAlignment
        ) {
            when (state) {
                is RequestState.Idle    -> onIdle?.invoke()
                is RequestState.Loading -> onLoading?.invoke()
                is RequestState.Error   -> onError?.invoke(
                    state.message, state.code, state.serverMessage, state.errorType
                )
                is RequestState.Success -> onSuccess(state.data)
                is RequestState.Empty   -> onEmpty?.invoke()
            }
        }
    }
}

displayResult is the flexible version. All callbacks except onSuccess are optional. If you don't pass onLoading, nothing renders during loading — useful for non-critical sections where a spinner would be distracting. The whole thing is wrapped in AnimatedContent, so every state transition cross-fades automatically.

Use displayResult when a screen section has custom loading or error UI that doesn't match the app defaults:

profileState.displayResult(
    onSuccess = { profile -> ProfileContent(profile) },
    onLoading = { ProfileLoadingSkeleton() },
    onError   = { message, _, serverMessage, _ ->
        NetworkErrorCard(
            onRetry = onRetry,
            errorMessage = serverMessage ?: message
        )
    }
)

`displayResultWithDefaults` — Convention Over Configuration

@Composable
fun <T> RequestState<T>.displayResultWithDefaults(
    onSuccess: @Composable (T) -> Unit,
    modifier: Modifier = Modifier,
    onLoading: (@Composable () -> Unit)? = { DefaultLoadingIndicator() },
    onIdle:    (@Composable () -> Unit)? = onLoading,
    onError:   (@Composable (String, Int?, String?, ResponseResult.ErrorType?) -> Unit)? = {
        errorMessage, _, serverError, _ ->
            DefaultErrorText(errorMessage = serverError ?: errorMessage)
    },
    onEmpty:   (@Composable () -> Unit)? = { DefaultEmptyContent() },
    transitionSpec: ContentTransform =
        fadeIn(tween(800)) togetherWith fadeOut(tween(800)),
    backgroundColor: Color? = null
) {
    AnimatedContent(
        modifier = modifier.background(color = backgroundColor ?: Color.Unspecified),
        targetState = this,
        transitionSpec = { transitionSpec },
        label = "ContentAnimation"
    ) { state ->
        when (state) {
            is RequestState.Idle    -> onIdle?.invoke()
            is RequestState.Loading -> onLoading?.invoke()
            is RequestState.Error   -> onError?.invoke(
                state.message, state.code, state.serverMessage, state.errorType
            )
            is RequestState.Success -> onSuccess(state.data)
            is RequestState.Empty   -> onEmpty?.invoke()
        }
    }
}

displayResultWithDefaults pre-wires app-wide defaults for each state:

Loading / Idle → DefaultLoadingIndicator() — your animated loading indicator
Error → DefaultErrorText() — server message if available, falls back to user message
Empty → DefaultEmptyContent() — a "no data found" placeholder

For the vast majority of screens, all you write is the success content — and override only what needs to be different:

uiState.categories.displayResultWithDefaults(
    onSuccess = { categories ->
        CategoryChips(
            items = categories,
            selectedItem = uiState.selectedCategory,
            onChipClick = { index, category ->
                viewModel.updateSelectedCategory(category, index)
            }
        )
    },
    onError = { message, _, serverMessage, _ ->
        NetworkErrorCard(
            onRetry = { viewModel.fetchCategories() },
            errorMessage = serverMessage ?: message
        )
    },
    onLoading = {
        CategoryChipsLoadingSkeleton(modifier = Modifier.fillMaxWidth())
    }
)

The convention handles the boilerplate. You handle the product logic.

The Full Loop

Here's the complete journey of a single data request, from first render to content on screen:

1. ViewModel initialises — field starts as Idle

val uiState = MutableStateFlow(UiState(categories = RequestState.Idle))

2. ViewModel fires the request — state transitions to Loading

executeNetworkCallWithState(
    call = { repository.fetchCategories() },
    onAllEvents = { state -> _uiState.update { it.copy(categories = state) } }
)
// onAllEvents fires with RequestState.Loading immediately

3. UI observes the StateFlow — renders loading state

val uiState by viewModel.uiState.collectAsState()

uiState.categories.displayResultWithDefaults(
    onSuccess = { categories -> CategoryChips(categories) }
)
// AnimatedContent fades in DefaultLoadingIndicator()

4. Request completes — state transitions to Success or Error

// onAllEvents fires with RequestState.Success(categories)
// _uiState updates, StateFlow emits

5. UI re-renders with the new state

// AnimatedContent cross-fades from loading indicator to category chips

One StateFlow. No separate loading boolean. No nullable data field to null-check. No error string to conditionally show. The state machine carries all of it.

When to Use Which

executeNetworkCall — use when the result updates a simple value or triggers a side effect. The data flows into a regular field, not a RequestState. Good for background loads where you don't need a loading skeleton: banner lists, notification counts, task reminders.

executeNetworkCallWithState — use when the RequestState itself should be stored in UiState. The UI needs to show loading skeletons and error retry buttons for this content.

displayResult — use when you need full control over every state's UI. The loading or error composable is unique to this context.

displayResultWithDefaults — use everywhere else. Consistent loading, error, and empty states across the whole app, with minimal code.

What We've Built

Across the first three parts, the full request lifecycle is covered end to end:

The HttpClient (Part 1) handles auth, retries, and connection concerns
ResponseResult and safeRequest (Part 2) handle every failure mode at the boundary and give repositories a typed return contract
RequestState, executeNetworkCall, executeNetworkCallWithState, and the displayResult extensions (this part) carry the result through the ViewModel into the UI with animated state transitions, consistent defaults, and zero boilerplate

A developer joining the team can look at any ViewModel or any screen Composable and immediately understand what's happening. State is always a RequestState. Network calls always go through executeNetworkCall or executeNetworkCallWithState. UI always renders through displayResult or displayResultWithDefaults.

What's Next

In Part 4, we'll extend this architecture into the three scenarios that every production app eventually hits: paginated lists with GenericPagingSource and PagingStateHandler, live data streams with WebSocketClientConnection and observeWebSocketMessages, and coordinated multi-source refresh with RefreshManager. None of them require new primitives — they all feed back into the same RequestState-based pattern you now know.

Found this useful? Drop a ❤️ or leave a comment — it helps more developers find the series.

Bulletproof Error Handling in Kotlin Multiplatform with ResponseResult and safeRequest

Shiva Thapa — Sat, 14 Mar 2026 14:26:27 +0000

Part 2 of 4 — This part builds on the Ktor HttpClient setup from Part 1. If you're jumping in here, the previous article covers the client configuration this layer sits on top of.

In Part 1, we built an HttpClient that handles authentication, retries, timeouts, and logging automatically. Every request leaves the client properly configured. But when the response comes back — what happens then?

In most codebases I've seen, the answer is: it depends on who wrote the repository. One repository wraps everything in a try-catch and returns null on failure. Another throws exceptions and lets the ViewModel sort it out. A third returns a Boolean. Over time, the UI layer ends up with an inconsistent patchwork of null checks, exception handlers, and loading state flags scattered across every screen.

The architecture in this series solves that problem at the data layer. The goal is simple: every network call, regardless of what it fetches or which repository it lives in, returns the same type. The UI always knows exactly what shape of data to expect. And nobody writes a try-catch in a repository ever again.

The two pieces that make this work are ResponseResult and safeRequest. Let's build them.

The Problem with Raw Exceptions

When you call client.get("some/endpoint") in Ktor, a lot can go wrong. The network might be down. The server might return a 403. The JSON might have a field with the wrong type. The request might time out. Each of these is a different exception class — IOException, ClientRequestException, SerializationException, HttpRequestTimeoutException, and more.

If you let those propagate up as exceptions, your ViewModel has to catch them. But which ones? What does it do with them? How does it distinguish between "no internet" and "user is unauthorized" and "server is down"? How does it get a user-friendly error message?

The answer shouldn't be: figure it out at call sites. The answer should be: wrap everything at the boundary, classify it, and give callers structured results.

That's exactly what ResponseResult does.

`ResponseResult` — The Return Type for Every Network Call

@Serializable
sealed class ResponseResult<out T> {

    @Serializable
    data class Success<out T>(val data: T? = null) : ResponseResult<T>()

    @Serializable
    data class Error(
        val message: String,
        val code: Int? = null,
        val serverMessage: String? = null,
        val errorType: ErrorType? = null
    ) : ResponseResult<Nothing>()

    @Serializable
    data object Empty : ResponseResult<Nothing>()

    @Serializable
    enum class ErrorType {
        NETWORK,
        SERVER,
        CLIENT,
        SERIALIZATION,
        TIMEOUT,
        UNAUTHORIZED,
        FORBIDDEN,
        NOT_FOUND,
        PAYMENT_NOT_VERIFIED, // domain-specific — adapt to your own app
        TICKET_NOT_GENERATED, // domain-specific — adapt to your own app
        UNKNOWN
    }

    companion object {
        fun <T> success(data: T? = null): ResponseResult<T> = Success(data)
        fun error(
            message: String,
            code: Int? = null,
            serverMessage: String? = null,
            errorType: ErrorType? = null
        ): ResponseResult<Nothing> = Error(message, code, serverMessage, errorType)
        fun empty(): ResponseResult<Nothing> = Empty
    }
}

Three states. That's all a network call can return.

Success<T> wraps the deserialized response body. The data is nullable because some successful responses carry no body — a 204 No Content, for instance. We model that with Empty rather than Success(null), but the nullable type gives you flexibility when mapping between layers.

Error carries four pieces of information. message is a user-facing string — something you can show directly on screen. serverMessage is the raw message from the server's error response, if one exists. code is the HTTP status code. And errorType is an enum that lets the UI or ViewModel branch on the kind of failure without string-matching error messages.

Empty represents a successful response with no body. This is meaningfully different from an error and deserves its own state.

The `ErrorType` Enum

The ErrorType enum is one of those things that looks like overkill until you actually need it. Consider what the UI needs to do differently for each of these:

UNAUTHORIZED — redirect to login
NETWORK — show "check your connection"
SERVER — show "something went wrong on our end, try again"
TIMEOUT — show "that took too long, try again"
NOT_FOUND — show "this content doesn't exist anymore"
PAYMENT_NOT_VERIFIED, TICKET_NOT_GENERATED — domain-specific flows unique to your app

Without ErrorType, the UI has to match on status codes or parse error strings to drive different behaviours. That's fragile. With ErrorType, you just when on it.

The custom types at the bottom (PAYMENT_NOT_VERIFIED, TICKET_NOT_GENERATED) are a production detail worth noticing. When your backend returns non-standard status codes for business logic errors — like 402 for an unverified payment or 424 for a failed ticket — you map them to domain-specific error types here. Replace these with whatever your own backend uses.

Transformation Operators

ResponseResult ships with a set of transformation functions that make it composable:

// Transform success data to another type — errors pass through unchanged
inline fun <R> map(transform: (T) -> R): ResponseResult<R>

// Chain results — useful when one result feeds into another
inline fun <R> flatMap(transform: (T) -> ResponseResult<R>): ResponseResult<R>

// Fold into a single value across all three states
inline fun <R> fold(
    onSuccess: (T?) -> R,
    onError: (message: String, code: Int?, serverMessage: String?, errorType: ErrorType?) -> R,
    onEmpty: () -> R
): R

// Inline callbacks for chaining
inline fun onSuccess(block: (T?) -> Unit): ResponseResult<T>
inline fun onError(block: (message: String, code: Int?, serverMessage: String?, errorType: ErrorType?) -> Unit): ResponseResult<T>
inline fun onEmpty(block: () -> Unit): ResponseResult<T>

// Extraction helpers
fun getOrNull(): T?
fun getOrElse(default: T): T
fun getOrThrow(): T

The map function is the one you'll use constantly in repositories. When your API returns a ResponseResult<UserDto> and you need to return a ResponseResult<User>, you call .map { it.toDomain() }. The mapping only runs if the result is a Success — errors and empty states pass through unchanged. No try-catch, no null check.

In a repository, this looks like:

override suspend fun fetchBanners(): ResponseResult<List<Banner>> {
    val response: ResponseResult<List<BannerDto>> =
        networkClient.safeRequest {
            url("some/endpoint/")
            method = HttpMethod.Get
        }
    return response.map { it.toDomain() }
}

The safeRequest call returns a ResponseResult<List<BannerDto>>. The .map transforms the DTO list into domain models. If the request failed, the Error passes straight through — the mapper function never executes. The caller gets back clean domain types with zero extra handling.

`safeRequest` — The Safety Net Around Every Request

safeRequest is an extension function on HttpClient. It's the only way we make HTTP requests in this codebase:

suspend inline fun <reified T> HttpClient.safeRequest(
    requestBuilder: HttpRequestBuilder.() -> Unit
): ResponseResult<T> {
    return try {
        val response = request { requestBuilder() }
        handleResponse<T>(response)
    } catch (e: Exception) {
        handleException(e)
    }
}

Three lines. Execute the request, handle the response, or catch any exception that escapes. The caller configures the request through requestBuilder — URL, method, body, parameters — and gets back a typed ResponseResult<T>.

Handling the Response

When the request completes without throwing, handleResponse maps the HTTP status code to the right ResponseResult:

suspend inline fun <reified T> handleResponse(response: HttpResponse): ResponseResult<T> {
    return try {
        when (response.status.value) {
            200, 201 -> ResponseResult.success(response.body<T>())

            204 -> ResponseResult.empty()

            401 -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "AuthError",
                    message = "Token expired or invalid",
                    userMessage = "Your session has expired. Please log in again to continue.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.UNAUTHORIZED
                )
            }

            403 -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "ForbiddenError",
                    message = "Access denied for resource",
                    userMessage = "You don't have permission to access this.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.FORBIDDEN
                )
            }

            404 -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "NotFoundError",
                    message = "Resource not found at ${response.request.url}",
                    userMessage = "We couldn't find what you're looking for. It may have been moved or removed.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.NOT_FOUND
                )
            }

            429 -> {
                val retryAfter = response.headers["Retry-After"]?.toLongOrNull() ?: 30L
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "RateLimitError",
                    message = "Rate limit exceeded. Retry after $retryAfter seconds",
                    userMessage = "You're doing that too fast. Please wait $retryAfter seconds and try again.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.CLIENT
                )
            }

            402 -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "PaymentNotVerified",
                    message = "Payment Not Verified",
                    userMessage = "We couldn't verify your payment. Please check your payment details or contact support.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.PAYMENT_NOT_VERIFIED
                )
            }

            424 -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "TicketNotGenerated",
                    message = "Ticket not generated",
                    userMessage = "Your payment was successful, but we ran into a problem issuing your ticket. Please contact support.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.TICKET_NOT_GENERATED
                )
            }

            in 400..499 -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "ClientError",
                    message = "Client error",
                    userMessage = "Something went wrong with your request. Please try again or contact support.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.CLIENT
                )
            }

            in 500..599 -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "ServerError",
                    message = "Server error",
                    userMessage = "We're experiencing a temporary issue on our end. Please try again in a few moments.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.SERVER
                )
            }

            else -> {
                val serverMessage = runCatching {
                    response.body<DefaultResponseDto<String>>().message
                }.getOrNull()
                logAndReturnError(
                    tag = "UnexpectedStatus",
                    message = "Unexpected response status: ${response.status}",
                    userMessage = "Something unexpected happened. Please try again or contact support.",
                    serverMessage = serverMessage,
                    statusCode = response.status.value,
                    errorType = ResponseResult.ErrorType.UNKNOWN
                )
            }
        }
    } catch (e: Exception) {
        handleException(e)
    }
}

A few patterns here worth calling out.

The serverMessage extraction uses runCatching:

val serverMessage = runCatching {
    response.body<DefaultResponseDto<String>>().message
}.getOrNull()

When a request fails, the server usually returns a JSON body explaining why — something like { "message": "This email is already registered." }. That message is often more informative than a generic "client error" string. But the error response might not always be parseable — the server might be down and return HTML, or the body might be empty. runCatching { }.getOrNull() extracts the server message silently when it's there, and returns null when it's not.

This is the purpose of DefaultResponseDto — a simple wrapper that matches the standard error envelope:

@Serializable
data class DefaultResponseDto<T>(
    @SerialName("data")    val data: T? = null,
    @SerialName("message") val message: String? = null,
    @SerialName("type")    val type: String? = null
)

If your backend uses a different envelope shape, adjust DefaultResponseDto accordingly. The pattern stays the same.

Specific status codes are handled before ranges. 402 and 424 are handled before the 400..499 catch-all. Kotlin's when evaluates branches top-to-bottom, so the specific cases win. This is how you map non-standard business logic codes to domain-specific ErrorType values without breaking the general client error handling.

The Retry-After header is read on 429:

val retryAfter = response.headers["Retry-After"]?.toLongOrNull() ?: 30L

When a server enforces rate limits, it often tells you how long to wait. Including that duration in the user-facing message is a small touch that makes a real difference in UX.

Handling Exceptions

When the request throws — not a failed HTTP response, but an actual exception — handleException classifies it:

@OptIn(ExperimentalSerializationApi::class)
inline fun <reified T> handleException(e: Exception): ResponseResult<T> {
    return when (e) {
        is SerializationException -> logAndReturnError(
            tag = "SerializationError",
            message = "Serialization failed: ${e.message}",
            userMessage = "We received an unexpected data format. Please try again or update the app.",
            exception = e,
            errorType = ResponseResult.ErrorType.SERIALIZATION
        )
        is JsonConvertException -> logAndReturnError(
            tag = "JsonConvertError",
            message = "JSON conversion failed: ${e.message}",
            userMessage = "We had trouble reading the server's response. Please try again.",
            exception = e,
            errorType = ResponseResult.ErrorType.SERIALIZATION
        )
        is MissingFieldException -> logAndReturnError(
            tag = "MissingFieldError",
            message = "Missing required field(s): ${e.missingFields.joinToString()}",
            userMessage = "We received incomplete information from the server. Please try again.",
            exception = e,
            errorType = ResponseResult.ErrorType.SERIALIZATION
        )
        is IOException -> logAndReturnError(
            tag = "NetworkIOError",
            message = "Network I/O error: ${e.message}",
            userMessage = "Couldn't connect to the server. Please check your internet connection and try again.",
            exception = e,
            errorType = ResponseResult.ErrorType.NETWORK
        )
        is SocketTimeoutException -> logAndReturnError(
            tag = "SocketTimeoutError",
            message = "Socket timeout: ${e.message}",
            userMessage = "The server is taking too long to respond. Please check your connection and try again.",
            statusCode = 408,
            exception = e,
            errorType = ResponseResult.ErrorType.TIMEOUT
        )
        is ConnectTimeoutException -> logAndReturnError(
            tag = "ConnectTimeoutError",
            message = "Connection timeout: ${e.message}",
            userMessage = "We couldn't reach the server. Please check your internet connection and try again.",
            statusCode = 408,
            exception = e,
            errorType = ResponseResult.ErrorType.TIMEOUT
        )
        is HttpRequestTimeoutException -> logAndReturnError(
            tag = "RequestTimeoutError",
            message = "Request timeout: ${e.message}",
            userMessage = "The request is taking longer than expected. Please try again in a moment.",
            statusCode = 408,
            exception = e,
            errorType = ResponseResult.ErrorType.TIMEOUT
        )
        is UnresolvedAddressException -> logAndReturnError(
            tag = "UnresolvedAddressError",
            message = "Failed to resolve address: ${e.message}",
            userMessage = "Couldn't reach the server. Please check your internet connection and try again.",
            exception = e,
            errorType = ResponseResult.ErrorType.NETWORK
        )
        is ClientRequestException -> logAndReturnError(
            tag = "ClientRequestError",
            message = "Client request failed with status ${e.response.status.value}",
            userMessage = "Something went wrong with your request. Please try again or contact support.",
            statusCode = e.response.status.value,
            exception = e,
            errorType = ResponseResult.ErrorType.CLIENT
        )
        is ServerResponseException -> logAndReturnError(
            tag = "ServerResponseError",
            message = "Server error with status ${e.response.status.value}",
            userMessage = "We're experiencing a temporary issue on our end. Please try again shortly.",
            statusCode = e.response.status.value,
            exception = e,
            errorType = ResponseResult.ErrorType.SERVER
        )
        is CancellationException -> logAndReturnError(
            tag = "CancellationError",
            message = "Request was cancelled: ${e.message}",
            userMessage = "The request was cancelled. Please try again if this wasn't intentional.",
            exception = e,
            errorType = ResponseResult.ErrorType.UNKNOWN
        )
        is WebSocketException -> logAndReturnError(
            tag = "WebSocketError",
            message = "WebSocket error: ${e.message}",
            userMessage = "Lost connection to the server. Please check your internet and try again.",
            exception = e,
            errorType = ResponseResult.ErrorType.NETWORK
        )
        else -> logAndReturnError(
            tag = "UnhandledException",
            message = "Unhandled exception: ${e::class.simpleName} - ${e.message}",
            userMessage = "Something unexpected happened. Please try again or contact support.",
            exception = e,
            errorType = ResponseResult.ErrorType.UNKNOWN
        )
    }
}

The exception map covers the full landscape of what Ktor can throw. Four categories:

Serialization failures (SerializationException, JsonConvertException, MissingFieldException) — the response body can't be parsed. Maybe the API changed a field type, or a required field is missing. SERIALIZATION signals to the UI that an app update might be needed.

Network failures (IOException, UnresolvedAddressException, WebSocketException) — the request never reached the server. The user is probably offline or on a flaky connection.

Timeout failures (SocketTimeoutException, ConnectTimeoutException, HttpRequestTimeoutException) — the server is reachable but slow. Prompt the user to try again.

HTTP-level exceptions (ClientRequestException, ServerResponseException) — Ktor throws these on 4xx/5xx when expectSuccess is enabled. With our handleResponse approach we handle status codes ourselves, but catching these as a fallback costs nothing.

CancellationException note: We deliberately catch it here rather than re-throwing it. In strict coroutine convention, CancellationException should be re-thrown. In our case the function returns a value rather than throwing — the call site sees an error result and moves on, while the coroutine itself is already being cancelled externally. The behaviour is correct. Be aware of this if you're adapting this code.

`logAndReturnError` — Structured Logging at the Boundary

inline fun <reified T> logAndReturnError(
    tag: String,
    message: String,
    userMessage: String,
    statusCode: Int? = null,
    serverMessage: String? = null,
    exception: Exception? = null,
    errorType: ResponseResult.ErrorType
): ResponseResult<T> {
    Logger.error(
        message = """
        [$tag] $message
        │ Exception: ${exception?.let { it::class.simpleName } ?: "N/A"}
        │ Message:   ${exception?.message ?: "No details"}
        │ Stacktrace: ${exception?.stackTraceToString() ?: "No stacktrace"}
        """.trimIndent()
    )

    return ResponseResult.error(
        message = userMessage,
        serverMessage = serverMessage,
        code = statusCode,
        errorType = errorType
    )
}

Every error path funnels through this one function. It logs the technical details — tag, internal message, exception class, full stacktrace — and constructs a ResponseResult.Error with a user-facing message. The separation is intentional: the log has everything a developer needs to diagnose the problem; the ResponseResult has what the UI needs to communicate it.

What a Repository Looks Like With This in Place

Here's a complete repository implementation. No try-catch, no error handling, no loading state:

class HomeRepositoryImpl(
    private val networkClient: HttpClient
) : HomeRepository {

    override suspend fun fetchBanners(): ResponseResult<List<Banner>> {
        val response: ResponseResult<List<BannerDto>> =
            networkClient.safeRequest {
                url("some/endpoint/")
                method = HttpMethod.Get
            }
        return response.map { it.toDomain() }
    }

    override suspend fun fetchCategoryItems(): ResponseResult<CategoryWithItems> {
        val response = networkClient.safeRequest<List<CategoryItemDto>> {
            url("some/endpoint/")
            method = HttpMethod.Get
        }
        return response.map { it.toDomain() }
    }

    override suspend fun submitFilterSelection(
        selectedItems: List<CategoryItem>
    ): ResponseResult<CategoryWithItems> {
        val response = networkClient.safeRequest<List<CategoryItemDto>> {
            url("some/endpoint/")
            setBody(selectedItems.toPayload())
            method = HttpMethod.Post
        }
        return response.map { it.toDomain() }
    }
}

Each function does three things: configure the request, make the call, map the result. The entire error surface — network down, server error, serialization failure, auth expiry — is handled by safeRequest and handleResponse, invisible to the repository. The repository's only job is to know the URL, the HTTP method, and how to map the DTO to a domain type.

This also makes repositories easy to test. You mock the HttpClient or the repository interface directly — no exception-throwing behaviour to account for.

A Note on the `DefaultResponseDto` Envelope

Many APIs wrap their success responses in an envelope too, not just errors. If your backend returns:

{
  "data": { ... },
  "message": "Success",
  "isVerified": true
}

Then your response type would be DefaultResponseDto<YourActualDataDto> and you'd map the inner data directly:

val response = networkClient.safeRequest<DefaultResponseDto<YourDataDto>> {
    url("your/endpoint/")
    method = HttpMethod.Get
}
return response.map { it.data?.toDomain() ?: throw IllegalStateException("Missing data") }

Or more cleanly with flatMap:

return response.flatMap { envelope ->
    envelope.data?.let { ResponseResult.success(it.toDomain()) } ?: ResponseResult.empty()
}

The operators on ResponseResult are designed exactly for this kind of layered unwrapping.

What We've Built

After this part, the networking layer has a complete, consistent error-handling contract:

Every repository function returns ResponseResult<T> — success, error, or empty
HTTP status codes are mapped to typed ErrorType values the UI can act on
Server error messages are extracted and forwarded when available
Every exception Ktor can throw is caught and classified
Technical errors go to logs; user-facing messages go to the UI
Repository code is three lines per function, with zero error handling

What's Next

The ViewModel still needs to react to these results — update loading state, show errors, navigate on success. In Part 3, we'll build the RequestState pattern and the executeNetworkCall / executeNetworkCallWithState functions that make that side of things just as clean. We'll also look at the displayResult Composable extension that lets your UI react to state changes in a single, animated, readable block.

Found this useful? Drop a ❤️ or leave a comment — it helps more developers find the series.

Setting Up Ktor the Right Way in Kotlin Multiplatform

Shiva Thapa — Sat, 14 Mar 2026 14:21:26 +0000

Part 1 of 4 — This series walks through a complete production networking architecture for Kotlin Multiplatform using Ktor.

There's a moment in every KMP project where things start feeling real. You've got your shared module wired up, your expect/actual declarations are in place, and now you need to make your first API call. So you add Ktor, write a quick HttpClient, make a request, and it works.

Then the app grows.

Suddenly you're dealing with token expiration on iOS, retry logic that keeps firing on 401s, WebSocket connections that need to stay alive across screens, and a team of developers who keep writing the same loading/error/success handling in slightly different ways across 20 different screens.

That's the problem this series exists to solve.

Over the next four parts, I'll walk you through the exact networking architecture we use in a production KMP application — one that runs on both Android and iOS, handles real users, and has been through enough edge cases to earn some opinions. We'll go from Ktor setup all the way through a request state pattern that makes your ViewModels and Composables a pleasure to work with, and through pagination and live WebSocket connections.

This first part covers the foundation: setting up Ktor in a KMP project correctly, and building an HttpClient that's ready for production from day one.

Why Ktor, and Why the Setup Matters

If you're coming from Android-only development, you probably lived on Retrofit + OkHttp. It's a great stack. But in KMP, Retrofit doesn't work in shared code. You need something that runs in commonMain, and Ktor is the answer.

Ktor is JetBrains' own async HTTP client, built on coroutines, and designed from the ground up for multiplatform. It uses platform-native engines under the hood — OkHttp on Android, Darwin (URLSession) on iOS — so you get native performance without writing platform-specific networking code. Everything you configure lives in commonMain.

But the way most people set up Ktor for the first time is far too simple for production. A single HttpClient() call with ContentNegotiation installed gets you making requests, but it doesn't get you:

Automatic token refresh that doesn't race condition itself
Smart retry logic that knows the difference between a server error and a 401
Consistent headers across every request
Logging that only runs in debug builds
WebSocket support with proper ping intervals

Let's build it properly.

Dependencies

Here's what you'll need in your libs.versions.toml. At the time of writing, Ktor 3.x is the current stable line:

[versions]
ktor = "3.4.0"

[libraries]
ktor-client-core                = { module = "io.ktor:ktor-client-core",                      version.ref = "ktor" }
ktor-client-okhttp              = { module = "io.ktor:ktor-client-okhttp",                     version.ref = "ktor" }
ktor-client-darwin              = { module = "io.ktor:ktor-client-darwin",                     version.ref = "ktor" }
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation",        version.ref = "ktor" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json",        version.ref = "ktor" }
ktor-client-auth                = { module = "io.ktor:ktor-client-auth",                       version.ref = "ktor" }
ktor-client-logging             = { module = "io.ktor:ktor-client-logging",                    version.ref = "ktor" }
ktor-client-websockets          = { module = "io.ktor:ktor-client-websockets",                 version.ref = "ktor" }

And in your build.gradle.kts shared module:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.ktor.client.core)
            implementation(libs.ktor.client.content.negotiation)
            implementation(libs.ktor.serialization.kotlinx.json)
            implementation(libs.ktor.client.auth)
            implementation(libs.ktor.client.logging)
            implementation(libs.ktor.client.websockets)
        }
        androidMain.dependencies {
            implementation(libs.ktor.client.okhttp)
        }
        iosMain.dependencies {
            implementation(libs.ktor.client.darwin)
        }
    }
}

The key insight here: ktor-client-core and all the plugins live in commonMain. The engine — OkHttp for Android, Darwin for iOS — is the only platform-specific piece. Your entire networking configuration, authentication logic, retry policies, and serialization happen once, in shared code.

The JSON Configuration

Before building the client, let's nail the JSON parser. This is one of those things that seems trivial until you're debugging a crash at 2am because an API returned an unexpected field.

object JsonConfig {
    val parser = Json {
        prettyPrint = true
        isLenient = true
        ignoreUnknownKeys = true
        useAlternativeNames = true
    }
}

ignoreUnknownKeys = true is non-negotiable. APIs evolve. The backend team will add new fields to responses, and you don't want your app crashing on old builds just because the server returned a field you haven't modelled yet. isLenient = true lets you handle slight JSON variations — empty strings where nulls might be expected, and similar real-world messiness. useAlternativeNames respects @JsonNames annotations, which is useful when you need to map multiple possible field names to a single property.

This JsonConfig object gets passed directly to the ContentNegotiation plugin later.

Building the HttpClient

Here's the full client factory, which we keep in an object called HttpNetworkClient:

object HttpNetworkClient {

    private const val BASE_URL = "https://yourdomain.com/api/"
    const val WSS_URL = "wss://yourdomain.com/"

    fun createHttpClient(
        authStateStore: AuthStateStore,
        sessionStateStore: SessionStateStore,
        appLocalizationRepository: AppLanguageStateStore,
        platformDetail: PlatformDetail,
        platformSpecific: PlatformSpecific
    ): HttpClient {
        return HttpClient {

            defaultRequest {
                url(BASE_URL)
                contentType(ContentType.Application.Json)
                accept(ContentType.Application.Json)

                headers.append("Device-Type", platformDetail.getPlatformName())
                headers.append("Device-Id", platformSpecific.getUniqueDeviceId() ?: "")
                headers.append("App-Version", platformDetail.getAppVersionName())
                headers.append(
                    "Accept-Language",
                    appLocalizationRepository.languagePreference.value.serverCode
                )

                val userAccessToken = authStateStore.userTokenData.value?.accessToken
                if (!userAccessToken.isNullOrBlank()) {
                    bearerAuth(userAccessToken)
                } else {
                    headers.remove(HttpHeaders.Authorization)
                }
            }

            install(ContentNegotiation) {
                json(json = JsonConfig.parser)
            }

            install(WebSockets) {
                pingInterval = 5000.milliseconds
            }

            install(HttpTimeout) {
                requestTimeoutMillis = 30_000L
                connectTimeoutMillis = 30_000L
                socketTimeoutMillis = 30_000L
            }

            install(Auth) {
                bearer {
                    refreshTokens {
                        return@refreshTokens try {
                            val newAccessToken = refreshBearerToken(authStateStore)
                            if (!newAccessToken.isNullOrBlank()) {
                                val currentRefreshToken =
                                    authStateStore.userTokenData.value?.refreshToken
                                BearerTokens(
                                    accessToken = newAccessToken,
                                    refreshToken = currentRefreshToken.orEmpty()
                                )
                            } else {
                                sessionStateStore.onSessionExpired()
                                null
                            }
                        } catch (ex: Exception) {
                            sessionStateStore.onSessionExpired()
                            null
                        }
                    }
                }
            }

            if (isDebugBuild()) {
                install(Logging) {
                    logger = object : io.ktor.client.plugins.logging.Logger {
                        override fun log(message: String) {
                            Logger.debug(message = message, tag = "NetworkClient")
                        }
                    }
                    level = LogLevel.BODY
                }
            }

            install(HttpRequestRetry) {
                maxRetries = 3
                retryIf { _, response ->
                    response.status.value in 500..599 ||
                    response.status == HttpStatusCode.RequestTimeout
                }
                exponentialDelay()
            }
        }
    }
}

Let's walk through each piece and the reasoning behind it.

`defaultRequest` — One Place for All Cross-Cutting Concerns

The defaultRequest block is where you set everything that should apply to every single request. The base URL, default content type and accept headers, and any custom headers your backend expects.

Notice the token injection:

val userAccessToken = authStateStore.userTokenData.value?.accessToken
if (!userAccessToken.isNullOrBlank()) {
    bearerAuth(userAccessToken)
} else {
    headers.remove(HttpHeaders.Authorization)
}

This runs on every request. If there's a token, it gets attached. If there isn't one — because the user isn't logged in — the Authorization header gets explicitly removed. That last part matters. Without it, you can end up in a state where Ktor tries to attach a null or empty token on public endpoints, which causes unexpected behaviour on some backends.

One thing to be aware of: defaultRequest is evaluated at request time, not at client creation time. So the token read here always reflects the current auth state. This is exactly what you want — you never want a stale token baked into the client at construction.

`ContentNegotiation` — Wiring in Your JSON Parser

install(ContentNegotiation) {
    json(json = JsonConfig.parser)
}

This connects your JsonConfig.parser to Ktor's serialization pipeline. Every response body you call .body<T>() on will be deserialized through this parser. Every request body you set with setBody() will be serialized through it too. One configuration, consistent everywhere.

`WebSockets` — The Ping Interval Is More Important Than It Looks

install(WebSockets) {
    pingInterval = 5000.milliseconds
}

If you plan to use WebSockets anywhere in your app — and we'll cover that in depth in Part 4 — you need to install the WebSocket plugin at the client level. The pingInterval of 5 seconds keeps the connection alive by automatically sending ping frames to the server. Without this, connections in mobile environments (with aggressive network management) will time out silently. You'll then spend an afternoon staring at logs wondering why messages stopped arriving.

`HttpTimeout` — All Three, Always

install(HttpTimeout) {
    requestTimeoutMillis = 30_000L
    connectTimeoutMillis = 30_000L
    socketTimeoutMillis = 30_000L
}

Set all three timeouts explicitly. requestTimeoutMillis is the total time for a request to complete. connectTimeoutMillis is how long to wait when establishing a connection. socketTimeoutMillis covers inactivity on the socket itself — useful for catching a server that accepts a connection but then goes silent.

30 seconds is a reasonable default for most APIs. For file upload or download endpoints, you'll want to override these per-request with a longer timeout.

`Auth` — Automatic Token Refresh Done Right

This is the most interesting part. Ktor's Auth plugin with bearer configuration handles the token refresh cycle automatically:

install(Auth) {
    bearer {
        refreshTokens {
            return@refreshTokens try {
                val newAccessToken = refreshBearerToken(authStateStore)
                if (!newAccessToken.isNullOrBlank()) {
                    val currentRefreshToken =
                        authStateStore.userTokenData.value?.refreshToken
                    BearerTokens(
                        accessToken = newAccessToken,
                        refreshToken = currentRefreshToken.orEmpty()
                    )
                } else {
                    sessionStateStore.onSessionExpired()
                    null
                }
            } catch (ex: Exception) {
                sessionStateStore.onSessionExpired()
                null
            }
        }
    }
}

Here's how Ktor's bearer auth flow works: when a request returns a 401 Unauthorized, Ktor automatically invokes refreshTokens. If that callback returns valid BearerTokens, Ktor retries the original request with the new access token — no extra code required. If refreshTokens returns null, Ktor stops retrying. That's your signal to log the user out, which is what sessionStateStore.onSessionExpired() does.

You'll notice we're not using loadTokens here. loadTokens introduces complications when the token gets cleared during logout — the plugin can end up re-attaching a stale cached token to requests even after auth state has been cleared. Instead, we read the token directly in defaultRequest, which always reflects live state.

Important: Ktor's Auth plugin handles its own retry cycle for 401 responses internally — it does not go through HttpRequestRetry. This is intentional. HttpRequestRetry is for server errors and timeouts. Auth handles 401s. Keep these concerns separate and you avoid a category of subtle infinite-loop bugs where token refresh and exponential backoff interact in unexpected ways.

The actual token refresh logic lives in a separate private function:

private suspend fun refreshBearerToken(authStateStore: AuthStateStore): String? {
    val refreshToken = authStateStore.userTokenData.value?.refreshToken ?: return null

    return try {
        val response = HttpClient {
            defaultRequest {
                url(BASE_URL)
                contentType(ContentType.Application.Json)
                accept(ContentType.Application.Json)
            }
            install(ContentNegotiation) {
                json(json = JsonConfig.parser)
            }
        }.request {
            url("token-refresh/")
            method = HttpMethod.Post
            contentType(ContentType.Application.Json)
            setBody(mapOf("refresh" to refreshToken))
        }

        if (!response.status.isSuccess()) return null

        val jsonBody = response.bodyAsText()
        val json = JsonConfig.parser.parseToJsonElement(jsonBody).jsonObject
        val newAccessToken = json["access"]?.jsonPrimitive?.content

        if (newAccessToken.isNullOrBlank()) return null

        updateTokens(newAccessToken, refreshToken, authStateStore)
        newAccessToken
    } catch (e: Exception) {
        null
    }
}

Notice we create a fresh, minimal HttpClient inside refreshBearerToken. This is deliberate. If we used the main client to make the refresh request, we'd create a circular dependency — the refresh call itself could trigger another refresh attempt, which would trigger another, and so on. A clean lightweight client with no auth plugin makes the refresh request unconditionally.

`Logging` — Debug Only, Always

if (isDebugBuild()) {
    install(Logging) {
        logger = object : io.ktor.client.plugins.logging.Logger {
            override fun log(message: String) {
                Logger.debug(message = message, tag = "NetworkClient")
            }
        }
        level = LogLevel.BODY
    }
}

LogLevel.BODY logs full request and response bodies, invaluable during development. The isDebugBuild() guard ensures this never runs in production. Routing output through your own Logger abstraction keeps logging consistent and makes it easy to swap logging libraries without touching this file.

`HttpRequestRetry` — Smart Retries for Real Failures

install(HttpRequestRetry) {
    maxRetries = 3
    retryIf { _, response ->
        response.status.value in 500..599 ||
        response.status == HttpStatusCode.RequestTimeout
    }
    exponentialDelay()
}

Three retries, only on 5xx server errors and request timeouts. exponentialDelay() uses the exponential backoff algorithm so retries don't hammer a struggling server. We explicitly do not retry on 4xx errors — those are client errors, retrying them is meaningless. We also do not retry on 401 — that's handled by the Auth plugin separately.

How the Client Gets Injected

The HttpNetworkClient.createHttpClient() factory function takes dependencies as parameters — auth state, session state, localization, platform details. With Koin, the setup looks like this:

single {
    HttpNetworkClient.createHttpClient(
        authStateStore = get(),
        sessionStateStore = get(),
        appLocalizationRepository = get(),
        platformDetail = get(),
        platformSpecific = get()
    )
}

The HttpClient instance is registered as a singleton. Every repository gets the same shared client instance — consistent configuration everywhere, no wasted resources from creating multiple client instances.

What We've Built

By the end of this setup, every network request in the app automatically gets:

The right base URL and content type headers
A bearer token if the user is logged in, no Authorization header if they're not
Custom headers like Device-Type, App-Version, and Accept-Language
Automatic token refresh on 401, with session expiry handling if refresh fails
JSON serialization through a single, lenient, well-configured parser
30-second timeouts across the board
Up to 3 retries with exponential backoff on server errors
Full request/response body logging in debug builds
WebSocket support ready to use

None of this requires any code in the repositories, ViewModels, or UI layers. It's declared once, in one place.

What's Next

An HttpClient gets you sending requests. But what happens when the response comes back — what do you actually do with it?

In Part 2, we'll build the ResponseResult sealed class and the safeRequest extension function: a complete, typed error-handling layer that maps every failure mode — network errors, timeouts, auth failures, serialization errors, custom HTTP status codes — into structured, actionable results that your repositories can return cleanly.

The goal is a networking layer where you never write a try-catch in a repository again.

Found this useful? Drop a ❤️ or leave a comment — it helps more developers find the series.

Debugging Kotlin Multiplatform Apps with Better Observability

Shiva Thapa — Sat, 07 Feb 2026 05:37:22 +0000

We’ve all been there. You have a Kotlin Multiplatform (KMP) app running beautifully on Android, but your iOS and other platform users are reporting a cryptic crash that you just can’t reproduce. You look at your logs, and all you see is a sea of println statements or disjointed Logcat/NSLog entries that tell you what happened, but never why.

In the multiplatform world, fragmented logging isn’t just a nuisance — it’s a blind spot. If your observability strategy changes every time you cross a platform boundary, you’re not just writing code; you’re building a puzzle you can’t solve.

That’s why I built KMP-Logger. It’s not just another logging wrapper; it’s a structured event pipeline designed to give you a single source of truth across Android, iOS, JVM, Web, and Desktop.

The “Chaos” of String-Based Logging

Most loggers treat logs as strings. But strings are for humans to read after things go wrong. Events are for systems to analyze before things get out of hand.

When you treat a log as a structured event, you gain four superpowers:

Searchability: Filter by specific User IDs or Request IDs across thousands of logs.
Efficiency: Messages aren’t even built if the log level is disabled.
Context: Metadata follows your execution flow through nested calls.
Consistency: Your JSON logs in Data log look the same whether they came from an iPhone or a Browser.

1. Choosing Your Entry Point: Simple vs. Structured

KMP-Logger respects where you are in your journey. Sometimes you’re prototyping at 2 AM and just need to see if a variable changed. Other times, you’re architecting a financial app that requires strict audit trails.

The “I just need to see this” API

For those quick moments, use the Log singleton. It’s zero-config and handles platform-native tagging automatically.

// Effortless tagging based on your class name
class AuthViewModel {
  private val log = Log.withClassTag()
  fun onLogin() {
    log.d("User tapped login button")
  }
}
class AuthViewModel {
  fun onLogin() {
    loggerD("User tapped login button") // Directly takes AuthViewModel as tag
  }
}
class AuthViewModel {
  fun onLogin() {
    Log.d("User tapped login button") // Simple logging, no initilization required
    // OR,
    Log.d("User tapped login button", "LoginTAG")
  }
}

The “This is for Production” API
When you’re ready for the big leagues, the StructuredLogger lets you attach deep metadata (Attributes) that travel with your log.

val logger = LoggerFactory.get("Checkout")
logger.info(attrs = { attr("cart_id", "cart_99") }) {
  "Processing payment for user_123"
}

2. The Secret Sauce: Context Propagation

Imagine you’re debugging a multi-step checkout flow. Passing a transactionId through ten different functions just for logging is a nightmare.

KMP-Logger’s LogContext acts like a “scaffold” for your logs. You set the context once, and every log emitted within that scope — no matter how deep — automatically inherits that metadata.

val sessionContext = LogContext(mapOf("sessionId" to "session_789"))
LogContextHolder.withContext(sessionContext) {
  // Every log inside here now knows the sessionId
  apiService.call()
  dbRepository.save()
}

3. A Pipeline That Grows With You

KMP-Logger isn’t a dead end. It’s a pipeline where you control the Style (Formatters) and the Destination (Sinks).

Smart Formatting

Want emojis in your console but clean JSON in your server?

PrettyLogFormatter: For developers who like their logs readable and visual.
JsonLogFormatter: For machine ingestion and cloud-native observability.

Pluggable Sinks

Logs should go where they are useful. Out of the box, you get native platform sinks, but the real power is in the custom implementations.

The Firebase Bridge
Need breadcrumbs for your crash reports? It’s a few lines of code:

class FirebaseLogSink : LogSink {
  override fun emit(event: LogEvent) {
    if (event.level < LogLevel.WARN) return
    val message = LogFormatters.json(false).format(event)
    FirebaseCrashlytics.getInstance().log(message)
  }
}

The “Privacy First” Sink
In the age of GDPR, you can’t just log everything. You can create a SanitizingSink that acts as a middleware, redacting sensitive keys like password or apiKey before they ever leave the device.

4. Precision Control (No More Log Noise)
Stop drowning in logs that you don’t always require. KMP-Logger allows you to set global defaults while providing surgical overrides for specific modules.

LoggerConfig.Builder()
.minLevel(LogLevel.INFO) // Stay quiet by default
.override("Database", LogLevel.VERBOSE) // Listen closely to DB queries
.override("NoisyLogs", LogLevel.OFF) // Silence the chatter
.build()

Conclusion: Observability is a Mindset
Logging isn’t optional. println doesn’t scale and it doesn’t tell you what actually went wrong.
A structured, multiplatform logging pipeline makes debugging predictable and your app more reliable.
KMP-Logger gives you consistent visibility across platforms — whether you’re starting fresh or untangling a legacy KMP codebase.

Ready to see clearly? Read full documentation here:
KMP-Logger on GitHub
Klibs.io

Happy building!

Enable Edge to Edge in Android Jetpack Compose (Transparent Status Bar)

Shiva Thapa — Mon, 06 May 2024 12:57:25 +0000

It is very common practice in android app world to go Edge to Edge to benefit from the full screen and improve app aesthetics. However, I have been asked and seen many questions for doing this in Jetpack Compose.

Rather going in details about the Window Insets let's see how to achieve edge to edge in android.

As the documentation already gives the instructions to enable edge to edge, there is a simple way a beginner, or a new project gets undesired result with status bar color on theme switch from Dark to Light.

To enable edge to edge,
Call enableEdgeToEdge() in Activity.onCreate. This will let your app display behind the system UI, that may be status bar, navigation bar, and other.

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        enableEdgeToEdge() // Add this line

        setContent {
            YourAppTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    ...
                }
            }
        }
    }
}

In your AndroidManifest.xml file set android:windowSoftInputMode=”adjustResize” inside activity. This let’s your app to receive the size of the software IME as insets (helpful to pad and lay out content).

<application
    <activity
          android:name=".MainActivity"
          android:exported="true"
          android:windowSoftInputMode="adjustResize" // Add this line
          ...
    </activity>
</application>

This is the recommended way to achieve edge to edge, however we get some undesired behavior when switching from Dark mode to Light mode.

With statusBarColor as primary, (primary color of material theme)

When statusBarColor is not set,
In Dark mode we get,

In Light mode we get,

The texts and icon color does not respond to the background color scheme. So, to fix this we need to make a little adjustment to our Theme.kt file in ui/theme package.

@Composable
fun YourAppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    ...
    val view = LocalView.current
    if (!view.isInEditMode) {
      SideEffect {
        val window = (view.context as Activity).window
//        window.statusBarColor = colorScheme.primary.toArgb()
        WindowCompat.getInsetsController(window, view).isAppearanceLightStatusBars = !darkTheme // negate darkTheme
      }
    }
    ...
}

You can entirely remove the section between “…”, or make changes as shown i.e. comment out the line which assigns the color for status bar, and negate darkTheme.

I want to remove that section, are there any affects removing it?
The answer to this is NO for a general use case.

What does it exactly do?
As isInEditMode name itself suggests, this allows you(developer) to write code that behaves differently during editing compared to when the app is actually running on a device. There is exactly no use case unless you specifically want to use it.

Also, if you are using custom material theme using theme builder then it will not be a problem as you can simply follow step 1 and 2 above.

I hope you can easily enable edge to edge now.

Addition to that, to achieve the desired padding and place layout appropriately, it’s a good practice to properly use Window Insets which you can learn from the documentation.

Apply SwipeToDismissBox in Android Jetpack Compose

Shiva Thapa — Thu, 02 May 2024 08:48:17 +0000

Here, let’s talk about the SwipeToDismissBox Composable which is more compose way to apply swipe to dismiss.

I hope you have seen the swipe feature in the Google’s Gmail app. It is a very handy feature which saves a lot of taps (clicks). Today, we will be implementing something like that using SwipeToDismissBox composable.

SwipeToDismissBox Composable

Firstly, I will introduce you to the different parameters that SwipeToDismissBox composable takes,

@Composable
@ExperimentalMaterial3Api
fun SwipeToDismissBox(
    state: SwipeToDismissBoxState,
    backgroundContent: @Composable RowScope.() -> Unit,
    modifier: Modifier = Modifier,
    enableDismissFromStartToEnd: Boolean = true,
    enableDismissFromEndToStart: Boolean = true,
    content: @Composable RowScope.() -> Unit,
) {...}

state: The state of this component.
backgroundContent: A composable that is stacked behind the main content and is visible when the main content is swiped or is being swiped.
enableDismissFromStartToEnd: Whether SwipeToDismissBox can be dismissed from start(left) to end(right).
enableDismissFromEndToStart: Whether SwipeToDismissBox can be dismissed from end(right) to start(left).
content: Our main content that can be dismissed.

SwipeToDismissBoxState

To achieve the behavior we want, we really need to play with SwipeToDismissBoxState. Thanks to developers behind this, we have very little to no things to worry about.

The rememberSwipeToDismissBoxState helps us remember and control the different SwipeToDismissBoxState values.

@Composable
@ExperimentalMaterial3Api
fun rememberSwipeToDismissBoxState(
    initialValue: SwipeToDismissBoxValue = SwipeToDismissBoxValue.Settled,
    confirmValueChange: (SwipeToDismissBoxValue) -> Boolean = { true },
    positionalThreshold: (totalDistance: Float) -> Float =
        SwipeToDismissBoxDefaults.positionalThreshold,
): SwipeToDismissBoxState {...}

Peeking into the parameters,

initialValue: It is the initial value of the state.
confirmValueChange: Optional callback for confirming or overriding a pending state change.
positionalThreshold: The distance from the start of a swipe where the target state is calculated. It’s added or subtracted from the origin offset based on swipe direction and is always a positive value.

Let’s understand its use with an example.

I have created a SwipeBox composable function to isolate it from other composables and make it reusable (in my case).

@OptIn(ExperimentalMaterial3Api::class)
@Composable
private fun SwipeBox(
    modifier: Modifier = Modifier,
    onDelete: () -> Unit,
    onEdit: () -> Unit,
    content: @Composable () -> Unit
) {
    val swipeState = rememberSwipeToDismissBoxState()

    lateinit var icon: ImageVector
    lateinit var alignment: Alignment
    val color: Color

    when (swipeState.dismissDirection) {
        SwipeToDismissBoxValue.EndToStart -> {
            icon = Icons.Outlined.Delete
            alignment = Alignment.CenterEnd
            color = MaterialTheme.colorScheme.errorContainer
        }

        SwipeToDismissBoxValue.StartToEnd -> {
            icon = Icons.Outlined.Edit
            alignment = Alignment.CenterStart
            color =
                Color.Green.copy(alpha = 0.3f)

        SwipeToDismissBoxValue.Settled -> {
            icon = Icons.Outlined.Delete
            alignment = Alignment.CenterEnd
            color = MaterialTheme.colorScheme.errorContainer
        }
    }
...

Here, I initialized some variables to store the icon, alignment property, and color which is assigned based on the dissmissDirection.

state.dismissDirection gives us the direction in which the composable is being dismissed. Using this we change the background of the SwipeToDismissBox for different actions i.e. on swipe left, and on swipe right.

To understand this more clearly, there are three directions (dragAnchors to be more specific) for dismissing by swipe. They are, StartToEnd, EndToStart, and Settled.

So, when the dismissDirection is in progress of any of three position we can call the composable that we want in the background. In our case, we assign the corresponding values for the icons, alignment property, and color, and then these properties are used in the backgroundContent below:

(You can directly call the composables unlike this case.)

...
SwipeToDismissBox(
        modifier = modifier.animateContentSize(),
        state = swipeState,
        backgroundContent = {
            Box(
                contentAlignment = alignment,
                modifier = Modifier
                    .fillMaxSize()
                    .background(color)
            ) {
                Icon(
                    modifier = Modifier.minimumInteractiveComponentSize(),
                    imageVector = icon, contentDescription = null
                )
            }
        }
    ) {
        content()
    }
...

Here, we set up the SwipeToDismissBox composable. I passed swipeState as state that I initialized before, and backgroundContent which is the composable that we want behind the main content. content() composable is the main content of our SwipeToDismissBox that we’ll get as an argument in our SwipeBox function.

Now, we would like to execute certain actions if the swipeState changes its positional value i.e. when the swipe is completed. In our case we’ll apply the onDelete() and onEdit() actions on dismissFromEndToStart and dismissFromStartToEnd respectively. We do this using the state’s .currentValue property which gives us the current state value.

...
    when (swipeState.currentValue) {
        SwipeToDismissBoxValue.EndToStart -> {
            onDelete()
        }

        SwipeToDismissBoxValue.StartToEnd -> {
            LaunchedEffect(swipeState) {
                onEdit()
                swipeState.snapTo(SwipeToDismissBoxValue.Settled)
            }
        }

        SwipeToDismissBoxValue.Settled -> {
        }
    }
}

As the code above speaks for itself, swipeState.currentValue property have three states i.e. EndToStart, StartToEnd, and Settled. When the swipeState is in any of the three state we can apply respective actions on them.

Here, when the EndToStart swipe completes I want to apply onDelete() action. Similarly, when the StartToEnd swipe completes I want to apply onEdit() action, and then set the state to the Settled position using snapTo function which takes the targetValue as an argument.

That’s it, our desired behavior has been achieved. This is just one way of doing it in countless others to achieve this behavior. There is always better way to do it.

Adding with it, there are many things to play with state such as:

progress() to get the progress status i.e. start 0f..1f end
targetValue() to get the closest state.
reset() to reset the component to default position.
dismiss() to dismiss the component in the given direction.

Complete Implementation

@OptIn(ExperimentalFoundationApi::class)
@Composable
fun DemoSwipeToDismiss(
    modifier: Modifier = Modifier
) {
    var myList by remember {
        mutableStateOf((1..3).toList())
    }

    LazyColumn(modifier = modifier) {
        items(myList) { item ->
            SwipeBox(
                onDelete = {
                    // Just for Example. Is not optimal!
                    myList = myList.toMutableList().also { it.remove(item) }
                },
                onEdit = { },
                modifier = Modifier.animateItemPlacement()
            ) {
                ListItem(headlineContent = { Text(text = "Headline text $item") },
                    supportingContent = { Text(text = "Supporting text $item") },
                    leadingContent = {
                        Icon(
                            imageVector = Icons.Outlined.AccountBox,
                            contentDescription = null
                        )
                    }
                )
            }
        }
    }
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
private fun SwipeBox(
    modifier: Modifier = Modifier,
    onDelete: () -> Unit,
    onEdit: () -> Unit,
    content: @Composable () -> Unit
) {
    val swipeState = rememberSwipeToDismissBoxState()

    lateinit var icon: ImageVector
    lateinit var alignment: Alignment
    val color: Color

    when (swipeState.dismissDirection) {
        SwipeToDismissBoxValue.EndToStart -> {
            icon = Icons.Outlined.Delete
            alignment = Alignment.CenterEnd
            color = MaterialTheme.colorScheme.errorContainer
        }

        SwipeToDismissBoxValue.StartToEnd -> {
            icon = Icons.Outlined.Edit
            alignment = Alignment.CenterStart
            color =
                Color.Green.copy(alpha = 0.3f) // You can generate theme for successContainer in themeBuilder
        }

        SwipeToDismissBoxValue.Settled -> {
            icon = Icons.Outlined.Delete
            alignment = Alignment.CenterEnd
            color = MaterialTheme.colorScheme.errorContainer
        }
    }

    SwipeToDismissBox(
        modifier = modifier.animateContentSize(),
        state = swipeState,
        backgroundContent = {
            Box(
                contentAlignment = alignment,
                modifier = Modifier
                    .fillMaxSize()
                    .background(color)
            ) {
                Icon(
                    modifier = Modifier.minimumInteractiveComponentSize(),
                    imageVector = icon, contentDescription = null
                )
            }
        }
    ) {
        content()
    }

    when (swipeState.currentValue) {
        SwipeToDismissBoxValue.EndToStart -> {
            onDelete()
        }

        SwipeToDismissBoxValue.StartToEnd -> {
            LaunchedEffect(swipeState) {
                onEdit()
                swipeState.snapTo(SwipeToDismissBoxValue.Settled)
            }
        }

        SwipeToDismissBoxValue.Settled -> {
        }
    }
}

Forem: Shiva Thapa

I Got Tired of Reverse-Engineering My Own Architecture. So I Built a Tool to See It.

The Problem Nobody Names Directly

What Already Exists (And Why It Wasn't Enough)

What Aalekh Does

The interactive graph

Cycle detection that doesn't lie to you

Architecture metrics

CI enforcement

How Aalekh Is Built Internally

Configuration cache compatibility

What's Coming in v0.2.0

Requirements

Try It

shivathapaa / Aalekh

Aalekh is a Gradle plugin that extracts, visualizes, and enforces architectural rules across any Gradle multi-module project - Kotlin Multiplatform, Android, JVM, or any Gradle project.

Aalekh

Sample Reports

Sample Report Demo

Why Aalekh?

Quick Start

Pagination, WebSockets, and Coordinated Refresh in Kotlin Multiplatform

Pagination with GenericPagingSource

Using It in a ViewModel

Pagination That Also Updates Other State

Rendering Pagination State with PagingStateHandler

The State Machine

The content Lambda Pattern

Per-Screen Customisation

Real-Time Data with WebSockets

WebSocketClientConnection

Connection and Reconnection

Incoming Message Processing

observeWebSocketMessages — Decoding and Routing in One Call

Using It in a ViewModel

Coordinated Refresh with RefreshManager

Pagination + WebSockets: How They Coexist on the Same Screen

Putting It All Together

From Data to UI with RequestState in Kotlin Multiplatform

The Gap Between Repository and UI

RequestState — UI State That Tells the Whole Story

Helper Functions

Transformation

Inline Callbacks

handleResult — For When You Need All Five Branches

executeNetworkCall — Wiring the Repository to the ViewModel

executeNetworkCallWithState — When the State Itself Lives in the ViewModel

The UiState Pattern

Bringing It to the UI — displayResult and displayResultWithDefaults

displayResult — Full Control

displayResultWithDefaults — Convention Over Configuration

The Full Loop

When to Use Which

What We've Built

What's Next

Bulletproof Error Handling in Kotlin Multiplatform with ResponseResult and safeRequest

The Problem with Raw Exceptions

ResponseResult — The Return Type for Every Network Call

The ErrorType Enum

Transformation Operators

safeRequest — The Safety Net Around Every Request

Handling the Response

Handling Exceptions

logAndReturnError — Structured Logging at the Boundary

What a Repository Looks Like With This in Place

A Note on the DefaultResponseDto Envelope

What We've Built

What's Next

Setting Up Ktor the Right Way in Kotlin Multiplatform

Why Ktor, and Why the Setup Matters

Dependencies

The JSON Configuration

Building the HttpClient

defaultRequest — One Place for All Cross-Cutting Concerns

ContentNegotiation — Wiring in Your JSON Parser

WebSockets — The Ping Interval Is More Important Than It Looks

HttpTimeout — All Three, Always

Auth — Automatic Token Refresh Done Right

Logging — Debug Only, Always

HttpRequestRetry — Smart Retries for Real Failures

Pagination with `GenericPagingSource`

Rendering Pagination State with `PagingStateHandler`

The `content` Lambda Pattern

`WebSocketClientConnection`

`observeWebSocketMessages` — Decoding and Routing in One Call

Coordinated Refresh with `RefreshManager`

`RequestState` — UI State That Tells the Whole Story

`handleResult` — For When You Need All Five Branches

`executeNetworkCall` — Wiring the Repository to the ViewModel

`executeNetworkCallWithState` — When the State Itself Lives in the ViewModel

The `UiState` Pattern

Bringing It to the UI — `displayResult` and `displayResultWithDefaults`

`displayResult` — Full Control

`displayResultWithDefaults` — Convention Over Configuration

`ResponseResult` — The Return Type for Every Network Call

The `ErrorType` Enum

`safeRequest` — The Safety Net Around Every Request

`logAndReturnError` — Structured Logging at the Boundary

A Note on the `DefaultResponseDto` Envelope

`defaultRequest` — One Place for All Cross-Cutting Concerns

`ContentNegotiation` — Wiring in Your JSON Parser

`WebSockets` — The Ping Interval Is More Important Than It Looks

`HttpTimeout` — All Three, Always

`Auth` — Automatic Token Refresh Done Right

`Logging` — Debug Only, Always

`HttpRequestRetry` — Smart Retries for Real Failures