DEV Community: Prem Singh

From Pixels to Text: Google ML Kit OCR on Android, with a KMP Core

Prem Singh — Fri, 30 Oct 2026 07:09:14 +0000

A receipt scanner looks simple in a demo: point the camera, recognize text, fill a form.

The engineering work starts when the receipt is rotated, the model is not ready, or an invoice number looks convincing but is wrong. A useful OCR feature handles those cases before it asks the user to trust the result.

Here is a practical architecture for Android capture and recognition, with a Kotlin Multiplatform core for the decisions that follow.

Choose the right job for each component

Google ML Kit Text Recognition v2 reads supported text from images. It is not an invoice parser or a guarantee that a recognized amount is correct.

Keep the workflow explicit:

Capture or import
      ↓
Prepare image + orientation
      ↓
Native OCR
      ↓
Shared normalization + candidate extraction
      ↓
Editable review screen
      ↓
User-confirmed save

For document capture on Android, ML Kit also has a separate Document Scanner API. Capture/cropping and text recognition are different steps; obtaining a scanned image or PDF does not mean your application already has structured OCR fields. Check that API's device and model requirements before selecting it.

Decide how the recognition model arrives

Android Text Recognition offers bundled and Google Play services-based options. Bundling increases app size but makes the model available with the app. An unbundled model must be downloaded before use; design a real preparation state rather than showing an unexplained empty result.

For Latin-script recognition, the bundled artifact is com.google.mlkit:text-recognition. The unbundled artifact is com.google.android.gms:play-services-mlkit-text-recognition. Choose one route and pin a compatible version from the official setup guide/release notes. Do not assume all target devices have Google Play services.

Text Recognition v2 supports Latin, Chinese, Devanagari, Japanese, and Korean scripts through the relevant SDKs. A Latin recognizer is not an Arabic recognizer. For Arabic or Urdu documents, evaluate an engine that explicitly supports the required script and test representative documents; do not silently promise coverage from a generic “OCR” label.

Keep the Android recognition adapter small

This integration sketch receives a prepared InputImage, reuses one Latin recognizer, and returns plain application data:

import com.google.mlkit.vision.common.InputImage
import com.google.mlkit.vision.text.TextRecognition
import com.google.mlkit.vision.text.latin.TextRecognizerOptions

data class OcrDocument(
    val fullText: String,
    val lines: List<String>,
)

class AndroidTextReader {
    private val recognizer = TextRecognition.getClient(
        TextRecognizerOptions.DEFAULT_OPTIONS
    )

    fun recognize(
        image: InputImage,
        onSuccess: (OcrDocument) -> Unit,
        onFailure: (Exception) -> Unit,
    ) {
        recognizer.process(image)
            .addOnSuccessListener { result ->
                onSuccess(
                    OcrDocument(
                        fullText = result.text,
                        lines = result.textBlocks.flatMap { block ->
                            block.lines.map { it.text }
                        },
                    )
                )
            }
            .addOnFailureListener { error -> onFailure(error) }
    }

    fun close() = recognizer.close()
}

This is an adapter sketch, not a complete scanner app. Its owner must manage request lifetime, errors, and teardown. Close the recognizer when finished with it, after in-flight work has settled; keep late callbacks from updating a screen that no longer owns the request.

For an imported image, InputImage.fromFilePath(context, uri) is an option; handle preparation failures and URI access lifetime. For CameraX frames, use the frame's actual rotation metadata when constructing the input image.

Flattened lines are enough for a simple candidate extractor. If layout matters, retain block/line bounds too and define their coordinate system. A visual document can have columns; do not assume flattening reconstructs the intended reading order.

Live camera OCR needs backpressure

Recognition is asynchronous. Starting work for every frame can create a queue of stale results.

With CameraX ImageAnalysis, use an appropriate backpressure strategy such as STRATEGY_KEEP_ONLY_LATEST. Keep the underlying image valid until recognition completes, then close the ImageProxy on success and failure. Close immediately if there is no usable image. Do not close the wrapped Media.Image directly.

If your app replaces an active scan with a new one, track request identity so an old callback cannot overwrite the new result. Dropping queued frames and ignoring obsolete UI results solve different problems.

For a first portfolio implementation, a captured still image is often easier to reason about than continuous OCR. Add live overlays only after the basic capture, review, and lifecycle paths work.

Share interpretation through KMP, not native image objects

Put a plain OcrDocument model and pure parsing functions in commonMain. The Android adapter maps ML Kit results into that model. An iOS adapter can use the native ML Kit iOS SDK or another suitable native recognizer and return the same application contract.

This does not mean Google's Android SDK runs in common Kotlin. Keep InputImage, Android Bitmap, and iOS image types at their platform boundaries. Agree on supported scripts, line ordering, coordinate conventions, and error meanings rather than assuming both engines behave identically.

For example, a deliberately narrow shared extractor could be:

fun invoiceIdCandidate(lines: List<String>): String? {
    val prefix = "Invoice ID:"
    return lines.asSequence()
        .map { it.trim() }
        .filter { it.startsWith(prefix, ignoreCase = true) }
        .map { it.substring(prefix.length).trim() }
        .firstOrNull { it.isNotEmpty() }
}

This only handles one label format. It returns a candidate, not a verified identifier. It will miss split labels, other languages, and some recognition errors. Keep fixtures for those cases and expand the rules intentionally instead of presenting a regex as document understanding.

Make the review screen part of the feature

Show the source image beside editable extracted fields. Distinguish “no text found” from processing failure and model preparation. Let the user recapture a blurred image without losing their other work.

Test rotations, small print, glare, multiple columns, mixed scripts, and ambiguous characters such as O/0 and I/1. Verify numeric formatting and currency conventions separately; do not automatically accept a financial value because OCR produced digits.

When recognition is poor, check focus, crop, lighting, and text size in the input before adding elaborate post-processing. A sharper capture often beats another parsing rule.

On-device OCR is not the whole privacy story

Google states that ML Kit processes input and recognition output on device rather than sending them to Google servers. Its SDK may still contact servers for models/updates and send performance/utilization metrics.

Your own app can still leak a receipt through logs, analytics, image backups, or an AI summarization request. Retain only what the feature needs, protect stored documents, and make any upload a separate deliberate action. On-device recognition does not authorize forwarding the extracted text elsewhere.

A portfolio demo worth showing

Record three short paths: a clean receipt, an unreadable capture that recovers gracefully, and a corrected field saved only after review. Add shared parser fixtures and platform integration checks. Explain model availability and supported scripts in the README.

That demonstrates a useful mobile product flow, not just a call to a recognition API.

References

Android Keystore and iOS Keychain: Protecting Mobile Data in the AI Era

Prem Singh — Thu, 29 Oct 2026 16:08:03 +0000

A token can be encrypted on disk and still leak through a debug log, a support screenshot, or an AI prompt.

Mobile security needs two boundaries: how data is protected while stored, and where plaintext is allowed to travel after the app reads it. Android Keystore and iOS Keychain help with the first. The second is an application design decision.

First, separate keys, secrets, and bulk data

What you have	A useful storage direction
Android encryption key	Generate and use it through Android Keystore
iOS token or small secret	Keychain item with explicit accessibility policy
Android token	Authenticated ciphertext in private storage, protected by an appropriate Keystore-managed key
Documents, attachments, large caches	Encrypted files or a suitable encrypted database, with separately protected key material
Shared AI-provider credential	Backend secret manager; do not ship it in the mobile app

Keystore is primarily a key-management facility. Keychain is also a store for small secrets. Neither should be treated as a place to dump an entire application database.

Android: protect the key, then encrypt the value

Android Keystore can keep key material non-exportable and constrain how a key is used. Hardware-backed protection depends on the device, algorithm, and configuration; do not assume every generated key lives in StrongBox.

This Kotlin snippet creates a new AES key for a new alias on API 23+:

import android.security.keystore.KeyGenParameterSpec
import android.security.keystore.KeyProperties
import javax.crypto.KeyGenerator
import javax.crypto.SecretKey

fun createNewStorageKey(alias: String): SecretKey {
    val generator = KeyGenerator.getInstance(
        KeyProperties.KEY_ALGORITHM_AES,
        "AndroidKeyStore",
    )
    generator.init(
        KeyGenParameterSpec.Builder(
            alias,
            KeyProperties.PURPOSE_ENCRYPT or
                KeyProperties.PURPOSE_DECRYPT,
        )
            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
            .setKeySize(256)
            .build()
    )
    return generator.generateKey()
}

This is key creation, not a complete storage wrapper. Do not call it on every read or silently replace an existing alias: old ciphertext still depends on its original key. Serialize first-use initialization and load the existing key for subsequent operations.

Use a platform-supported authenticated encryption construction, such as AES/GCM/NoPadding. On encryption, let the provider generate a fresh IV and persist the IV with the ciphertext and authentication tag. Never reuse a GCM nonce with the same key. Authenticate on decryption and reject modified data.

An ordinary Keystore key is not automatically gated by a new biometric prompt. Configure authentication requirements deliberately when the use case needs them, and design for lock state, cancellation, and key invalidation. A compromised process may still invoke allowed key operations even when it cannot extract the key.

iOS: store a small secret with an explicit access policy

For a foreground-only credential that should not migrate to another device, a Keychain add operation can look like this:

import Foundation
import Security

func addNewSecret(
    _ value: Data,
    service: String,
    account: String
) throws {
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrService as String: service,
        kSecAttrAccount as String: account,
        kSecAttrAccessible as String:
            kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
        kSecValueData as String: value,
    ]
    let status = SecItemAdd(query as CFDictionary, nil)
    guard status == errSecSuccess else {
        throw NSError(domain: NSOSStatusErrorDomain, code: Int(status))
    }
}

This intentionally adds only a new item. Handle errSecDuplicateItem using a narrowly matched SecItemUpdate when updating is intended; do not delete and recreate a credential on every save. Define service/account namespaces and access groups deliberately.

Choose accessibility around actual behavior:

WhenUnlockedThisDeviceOnly: available while unlocked; does not migrate to a different device through backup restoration.
AfterFirstUnlockThisDeviceOnly: can support access while locked after the first unlock since restart, with a broader availability window.
WhenPasscodeSetThisDeviceOnly: requires a device passcode; removing it deletes items in this class.

ThisDeviceOnly is a migration restriction, not a claim that the item can never appear in a same-device backup. Explicitly define synchronization and recovery requirements.

If user presence is required at retrieval, use Keychain access controls tied to the operation. A separate Face ID screen does not automatically protect every later read. Also, Keychain is not synonymous with Secure Enclave: placing an arbitrary AES key in Keychain does not make it a non-exportable Secure Enclave AES key.

Treat errSecItemNotFound, temporary interaction restrictions, and authentication cancellation differently. Deleting a credential because a locked-device read failed can turn a recoverable condition into data loss.

What if the app has much more data?

For larger datasets, protect the data where it belongs—files or a database—and protect the keys separately.

A possible envelope-encryption design is:

Platform-protected key material
          |
          v
protects a random data-encryption key
          |
          v
authenticated encrypted files / database content

On Android, a non-exportable Keystore key can wrap a random data key. On iOS, a symmetric data key can be stored as a protected Keychain item. These mechanisms have different properties; an iOS symmetric key retrieved into the process is still present in application memory.

Record a versioned format, algorithm, key identifier, nonce, ciphertext, and tag as appropriate. Associated data can bind ciphertext to an expected account/record context, but is authenticated rather than encrypted. Use trusted context during decryption; merely trusting metadata supplied alongside an attacker's ciphertext does not enforce account isolation.

For large files, use a vetted streaming authenticated-encryption implementation rather than inventing chunking, nonce allocation, or tag rules. Google's Tink Streaming AEAD is one option for supported environments; its Objective-C implementation does not offer the same streaming primitive. Verify platform support and the file format before promising Android/iOS interoperability.

For a database, evaluate a maintained encryption implementation, including its journals, write-ahead logs, temporary files, and key-handling behavior. Room and DataStore do not automatically provide application-level encryption simply because the app uses them. Platform file protection is useful, but does not replace your chosen key and backup policy.

Encryption at rest does not authorize a server request, hide plaintext from your own running code, or stop every attack on a compromised device.

The AI-era failure happens after decryption

Imagine an assistant that summarizes a customer's document. The app decrypts it correctly, then uploads the entire text and a diagnostic token to a model endpoint. Local encryption worked; the data-disclosure boundary failed.

Make that boundary explicit:

Keep shared provider credentials on your backend. A key embedded in an APK or IPA is distributable to the person running the app, even if obfuscated or encrypted with another bundled secret.
Authenticate users, enforce authorization, limit spending/rate, and constrain operations server-side. For direct provider access, use purpose-built, short-lived, narrowly scoped credentials where supported.
Send only the content required for the requested feature. Prefer synthetic/redacted examples when debugging with AI tools; exclude tokens, private keys, customer records, and production dumps.
Check provider retention, training use, access, and deletion controls for the actual account and service. Do not assume every endpoint has the same policy.
Treat retrieved text and model output as untrusted. Enforce permissions in application/tool code, not in a prompt saying “never reveal secrets.”
Review prompt traces, crash reports, analytics, clipboard actions, and support exports. They can bypass otherwise careful storage design.

For local models, the network disclosure risk may change, but prompt history, caches, embeddings, logs, and tool permissions still need protection. “On device” is a location, not a complete security policy.

Plan the moments when keys disappear

Decide what happens after uninstall, restore to a new device, account removal, or key invalidation. Device-bound keys and restored ciphertext may not remain usable together. Test backup exclusions and recovery instead of discovering the mismatch after release.

On logout, revoke server sessions where appropriate and remove account-scoped secrets and cached plaintext. Key deletion can render ciphertext unusable, but is not proof that every backup, exported copy, or flash-storage remnant vanished. Recovery, retention, and deletion are separate requirements.

Before shipping, verify tampered ciphertext is rejected, nonce handling survives repeated writes, locked-device reads fail safely, accounts cannot read each other's records, and diagnostic/AI flows never receive unintended plaintext.

Protect the key, minimize the plaintext lifetime, and make every boundary after decryption intentional.

References

Offline-First Mobile: A Refresh Error Should Not Erase Good Data

Prem Singh — Thu, 29 Oct 2026 01:53:40 +0000

Open a mobile app on a weak connection. A list appears from yesterday's cache, refresh starts, the request fails—and the entire screen becomes an error page.

The app had useful data. Its state model simply had nowhere to put both that data and a refresh failure.

This is a practical design problem for Android and Kotlin Multiplatform: content availability and refresh status are different facts.

Model two dimensions

An exclusive Loading / Success / Error model is convenient for an initial request. It becomes restrictive when a screen can show cached content while refreshing.

Consider this shared presentation model:

data class ArticleSummary(val id: String, val title: String)

sealed interface RefreshStatus {
    data object Idle : RefreshStatus
    data object Running : RefreshStatus
    data object Failed : RefreshStatus
}

data class ArticleListState(
    val items: List<ArticleSummary> = emptyList(),
    val hasLocalSnapshot: Boolean = false,
    val refresh: RefreshStatus = RefreshStatus.Idle,
)

hasLocalSnapshot distinguishes “we have never loaded data” from “we loaded an empty list.” Without that distinction, a legitimate empty response can look like unfinished loading forever.

The refresh state answers whether synchronization is happening. It does not replace the content.

Give reads one route

For a read-only feed, a useful repository contract is:

import kotlinx.coroutines.flow.Flow

interface ArticleRepository {
    fun observeLocal(): Flow<List<ArticleSummary>?>
    suspend fun refresh()
}

Here, null means no stored snapshot yet, while an empty list is a stored empty result. This is one possible contract, not a universal database convention.

The UI observes the local stream. A refresh fetches remote data and commits the accepted result to local storage. The local observation then supplies the updated content. Avoid making the screen race a network result against a separate database result.

Persistence, networking, and scheduling still need implementations appropriate to the supported platforms. A shared repository interface does not make Android background execution APIs portable to iOS.

Keep failure from becoming deletion

This conceptual refresh sequence makes the ordering visible:

mark refresh as running
fetch the remote snapshot
validate and map the response
commit the accepted snapshot atomically
mark refresh as idle

on expected refresh failure:
    retain the local snapshot
    mark refresh as failed

Do not clear storage at the start of refresh. A failed request should not destroy data merely to make room for a result that never arrives.

However, retaining everything forever is not a synchronization strategy. A successful authoritative empty snapshot may need to remove old rows. A paginated response normally cannot replace the entire dataset. Define whether the response is a complete snapshot, a page, or a delta before choosing a database operation.

Turn combinations into UI decisions

Local state	Refresh state	Useful presentation
No snapshot	Running	Initial loading view
No snapshot	Failed	Full error with retry
Cached items	Running	Existing list with refresh indicator
Cached items	Failed	Existing list with a retry message
Stored empty result	Idle	Intentional empty state

These are product choices, but making them explicit prevents accidental behavior. Show a “last updated” value when freshness matters, using persisted metadata rather than the time the composable happened to render.

Handle the next race before it ships

If two refreshes overlap, an older response can arrive after a newer one. Pick a policy: serialize refreshes, cancel obsolete work where appropriate, or reject responses using a suitable version check. A database transaction prevents a partially written snapshot; it does not automatically decide which response is newest.

Account changes also need ownership rules. Partition or clear account-specific data deliberately and cancel old work so a previous user's response cannot populate the next user's screen.

For edits and queued writes, go further: define durable operations, server deduplication, conflict handling, and how pending state is shown. A cached read feed alone is not a complete offline synchronization engine.

Verify the behavior users notice

Test a stored non-empty list followed by a refresh failure. The list should remain. Then test an accepted empty snapshot, restart the process, and confirm the app still knows the result was empty.

That pair of cases often reveals more than a successful network demo. Offline-first behavior starts with preserving a coherent local view and making uncertainty visible.

References

KMP Coroutine Tests: Test Time Without Waiting for It

Prem Singh — Thu, 29 Oct 2026 01:50:34 +0000

A test that sleeps for a second to verify a one-second delay is slow by design. A test that sleeps a little longer to avoid failing on CI is also difficult to trust.

For shared coroutine logic, virtual time gives you a better question: what should have happened before this deadline, and what should happen at it?

Make the delayed behavior small

Here is a deliberately tiny piece of shared code:

import kotlinx.coroutines.delay

class DelayedRefresh(
    private val refresh: suspend () -> Unit,
) {
    suspend fun run() {
        delay(1_000)
        refresh()
    }
}

The delay is only an example. In a real feature, a product rule should justify it. The important design choice is that the class suspends in its caller's coroutine instead of creating an unrelated scope.

Assert the boundary explicitly

Put this test in commonTest with kotlin.test and kotlinx-coroutines-test dependencies:

import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.launch
import kotlinx.coroutines.test.advanceTimeBy
import kotlinx.coroutines.test.runCurrent
import kotlinx.coroutines.test.runTest
import kotlin.test.Test
import kotlin.test.assertEquals

@OptIn(ExperimentalCoroutinesApi::class)
class DelayedRefreshTest {
    @Test
    fun refreshRunsAtTheDeadline() = runTest {
        var refreshes = 0
        val action = DelayedRefresh { refreshes++ }

        val job = launch { action.run() }
        runCurrent()

        advanceTimeBy(999)
        assertEquals(0, refreshes)

        advanceTimeBy(1)
        runCurrent()
        assertEquals(1, refreshes)

        job.join()
    }
}

The first runCurrent() starts the launched coroutine and reaches its delay. Advancing by 999 ms proves the work has not fired early. Advancing to 1,000 ms moves the clock to the deadline; runCurrent() executes work scheduled at that instant.

This distinction matters because advanceTimeBy does not itself run tasks scheduled exactly at the destination time. Treating clock movement and task execution as separate steps makes boundary assertions easier to read.

Test cancellation as a feature

Add a second test to the same class:

@Test
fun cancellationPreventsRefresh() = runTest {
    var refreshes = 0
    val action = DelayedRefresh { refreshes++ }

    val job = launch { action.run() }
    runCurrent()
    advanceTimeBy(500)

    job.cancel()
    job.join()

    advanceTimeBy(1_000)
    runCurrent()
    assertEquals(0, refreshes)
}

A completed success test cannot prove that obsolete work stops. This cancellation test expresses a separate requirement: cancelling the owner before the deadline must prevent the refresh.

Virtual time has a boundary too

The test scheduler controls work using its test dispatchers. It does not accelerate a real server, blocking sleep, or arbitrary work moved to a production dispatcher.

When a class must switch dispatcher, inject that dispatcher and use a StandardTestDispatcher(testScheduler) in the test. Keep related test dispatchers on the same scheduler. Otherwise, advancing one clock may not advance the work you intended to observe.

Keep runTest as the returned result of the test function, as shown above, for cross-platform compatibility. Avoid placing unrelated work after it.

What this still does not prove

A passing common test validates the shared behavior on the targets where you actually run it. Merely placing a test in commonTest is not evidence that CI executed every target.

Discover the test tasks exposed by your module, run the relevant Android/JVM and native targets, and respect host requirements for Apple targets. Native integration and UI behavior deserve their own tests.

For timing-sensitive code, a useful test tells a short story: start work, advance to just before the boundary, assert, cross the boundary, assert again. That is more informative than waiting and hoping the final state appears.

References

KMP Architecture: Share the Contract, Keep the Platform Details

Prem Singh — Thu, 29 Oct 2026 01:49:00 +0000

The first difficult Kotlin Multiplatform decision is often not how much code to share. It is where platform behavior should enter the shared code.

Take an article reader that opens an external link. Android needs an appropriate Context and intent. iOS needs its own application APIs. Shared presentation logic only needs to request an action and handle its outcome.

That is a useful place for a small contract.

Start with the caller's needs

Put the following in commonMain:

enum class OpenLinkResult { Opened, Unavailable }

interface ExternalLinkOpener {
    suspend fun open(url: String): OpenLinkResult
}

class ArticleActions(
    private val linkOpener: ExternalLinkOpener,
) {
    suspend fun openSource(url: String): OpenLinkResult {
        if (!url.startsWith("https://")) {
            return OpenLinkResult.Unavailable
        }
        return linkOpener.open(url)
    }
}

This deliberately small example rejects non-HTTPS input. A real application still needs URI parsing and any product-specific host rules; checking a prefix is not a security validation strategy.

The dependency describes a capability. It does not expose an Android Context, an Intent, or an iOS application object to every caller.

Also define what Opened means: the platform accepted the handoff, not that the page loaded or the user read it. Clear semantics make the contract useful across platforms.

Inject an implementation at the edge

Each platform creates its implementation and passes it to ArticleActions. Constructor injection is enough; a dependency injection framework is optional.

Android entry point -> AndroidLinkOpener -> ArticleActions
iOS entry point     -> IOSLinkOpener     -> ArticleActions
commonTest          -> FakeLinkOpener    -> ArticleActions

Keep platform thread requirements, lifecycle handling, and native error translation in the adapters. A suspend declaration does not automatically switch threads or make a platform call cancellable.

If the adapter performs suspending work, preserve coroutine cancellation instead of turning it into an ordinary Unavailable result. Convert expected platform failures deliberately; do not blanket-catch every programming error.

Where expect/actual fits

When the shared module should provide its own construction entry point, an expected factory can return the interface:

// commonMain
expect fun createExternalLinkOpener(): ExternalLinkOpener

The corresponding actual functions belong to the relevant platform source sets and package. Their implementations are omitted here because construction may require platform dependencies. A no-argument factory is only suitable when those dependencies can be obtained appropriately; otherwise pass them at a platform entry point.

The interface and expect/actual serve different purposes. The interface is the behavior contract. The factory selects a construction path. You do not need an expected class for every platform service.

Test behavior without opening a browser

This common test verifies that an unsupported scheme never reaches the platform adapter:

import kotlinx.coroutines.test.runTest
import kotlin.test.Test
import kotlin.test.assertEquals

class ArticleActionsTest {
    @Test
    fun unsupportedSchemeDoesNotReachAdapter() = runTest {
        var calls = 0
        val fake = object : ExternalLinkOpener {
            override suspend fun open(url: String): OpenLinkResult {
                calls++
                return OpenLinkResult.Opened
            }
        }

        val result = ArticleActions(fake).openSource("file:///notes")

        assertEquals(OpenLinkResult.Unavailable, result)
        assertEquals(0, calls)
    }
}

Use kotlin.test and kotlinx-coroutines-test in commonTest, aligned with your project versions. The snippets describe a module design, not a complete app setup.

This test checks the shared decision. Platform tests still need to verify the actual handoff, valid URLs, unavailable handlers, and lifecycle behavior.

A useful boundary review

Before introducing a platform abstraction, ask:

Does the caller need a capability, or the native object itself?
Can the outcome mean the same thing on every supported platform?
Who supplies platform dependencies and owns their lifetime?
Can a fake verify shared behavior without pretending to test native integration?

Share policy and intent where they are genuinely common. Keep native mechanics at a boundary you can explain and test.

References

Your AI Feature Deserves Better Than a Spinner: A Jetpack Compose Response Card

Prem Singh — Sun, 18 Oct 2026 07:38:22 +0000

An AI response can take a moment. During that pause, the interface has a job: explain what is happening, preserve context, and give the user a way forward.

Let's design a compact response card for an Android writing assistant. The visual direction is simple: a rounded Material surface, a clear heading, generous spacing, and one primary action. The interesting part is how the card behaves when the answer isn't ready.

This is a UI implementation example, not an AI integration. The response text is supplied by the caller. No model, API key, or network request is involved.

Start with four explicit states

Avoid a collection of independent booleans such as isLoading, hasError, and hasResult. Those can accidentally describe contradictory combinations.

sealed interface AssistantState {
    data object Idle : AssistantState
    data object Loading : AssistantState
    data class Answer(val text: String) : AssistantState
    data object Error : AssistantState
}

Each state should answer a user question:

State	What the interface explains
Idle	What can I do here?
Loading	Did my action start?
Answer	What did I get back?
Error	How can I recover?

Build the card around state and events

The following snippet uses Compose Foundation, Animation, and Material 3 inside an existing Compose app. Include the standard imports from those libraries. It is an illustrative snippet; it has not been compiled or device-tested as a standalone project.

@Composable
fun AssistantCard(
    state: AssistantState,
    onGenerate: () -> Unit,
    modifier: Modifier = Modifier,
) {
    val colors = MaterialTheme.colorScheme

    Surface(
        modifier = modifier.fillMaxWidth(),
        shape = RoundedCornerShape(28.dp),
        color = colors.surfaceContainer,
        tonalElevation = 2.dp,
    ) {
        Column(
            modifier = Modifier.padding(24.dp),
            verticalArrangement = Arrangement.spacedBy(16.dp),
        ) {
            Text(
                text = "Writing assistant",
                style = MaterialTheme.typography.titleLarge,
                color = colors.onSurface,
            )
            Text(
                text = "Turn a rough note into a clearer draft.",
                style = MaterialTheme.typography.bodyMedium,
                color = colors.onSurfaceVariant,
            )

            AnimatedContent(
                targetState = state,
                label = "assistant_content",
                modifier = Modifier.fillMaxWidth(),
            ) { current ->
                when (current) {
                    AssistantState.Idle -> Text(
                        "Ready when you are.",
                        color = colors.onSurface,
                    )
                    AssistantState.Loading -> Row(
                        horizontalArrangement = Arrangement.spacedBy(12.dp),
                        verticalAlignment = Alignment.CenterVertically,
                    ) {
                        CircularProgressIndicator(
                            modifier = Modifier.size(24.dp),
                            strokeWidth = 2.dp,
                        )
                        Text("Preparing your draft…", color = colors.onSurface)
                    }
                    is AssistantState.Answer -> Text(
                        text = current.text,
                        style = MaterialTheme.typography.bodyLarge,
                        color = colors.onSurface,
                    )
                    AssistantState.Error -> Text(
                        text = "Couldn't prepare a draft. Please try again.",
                        color = colors.error,
                    )
                }
            }

            Button(
                onClick = onGenerate,
                enabled = state != AssistantState.Loading,
                modifier = Modifier.fillMaxWidth(),
            ) {
                Text(
                    when (state) {
                        AssistantState.Loading -> "Preparing…"
                        AssistantState.Error -> "Try again"
                        is AssistantState.Answer -> "Generate another draft"
                        AssistantState.Idle -> "Generate draft"
                    }
                )
            }
        }
    }
}

The card receives immutable state and emits an event. It doesn't own the request. This makes it easier to preview each state and connect the same interface to a fake response or a real service. Choose the state owner based on the logic involved; business logic typically belongs in a screen-level state holder such as a ViewModel. See the Android state-hoisting guidance.

AnimatedContent uses its lambda parameter (current) to render the transitioning state. Keep that detail: reading the outer state instead can break the intended transition behavior. The official animation documentation explains the API.

The details that make it feel finished

Use motion to explain change. A gentle content transition is enough here. Constant shimmer or a dramatic glow can compete with the answer. For streamed responses, keep the answer container stable rather than restarting a transition for every token.

Be honest about progress. This example shows indeterminate progress. Display a percentage only when the underlying work can actually measure it.

Design the recovery path. An error message without an action is a dead end. Preserve the original input outside this card so retry doesn't require typing it again. A real request owner should also reject duplicate requests and handle cancellation.

Check more than the screenshot. Test large font sizes, dark mode, long answers, and TalkBack. This sample leaves announcements to the surrounding screen; consider a concise polite live-region announcement when a result becomes available. Avoid announcing every streamed token. Read the Compose semantics guidance.

Keep the result identifiable. Label AI-generated output and let the user review it before using it elsewhere. A polished surface should never imply the answer has been verified.

Try it in your next Compose experiment

Render the card in all four states before connecting a model. If the loading and error views feel like afterthoughts, the feature isn't finished yet.

What would you add next: cancellation, editable output, or a copy action?

Prem Singh · Lead Android Engineer · Kotlin, Jetpack Compose, and practical Android engineering

GitHub · LinkedIn

Beyond the Run Button: Android Debugging with ADB and Gradle

Prem Singh — Sun, 18 Oct 2026 03:38:16 +0000

“It works when I press Run” is a starting point. A useful debugging workflow also lets another developer reproduce the same build, launch the same route, and collect evidence of the failure.

Here is a compact terminal workflow for a debug app. Each step answers a question rather than adding another command to memorize.

Before you start

Examples use macOS/Linux shell syntax, an app module, and a debug variant. On Windows, use gradlew.bat and adapt shell variables and quoting. Run Gradle commands from the project root. Your configured JDK must be compatible with the project's Android Gradle Plugin.

Have SDK Platform Tools on your PATH and an authorized test device or emulator connected:

adb devices -l
export ANDROID_SERIAL=emulator-5554

Replace the serial with one from the output. ANDROID_SERIAL selects the target for subsequent ADB commands. An unauthorized device needs approval on the unlocked device.

1. Can someone else build this exact variant?

Use the project's Gradle Wrapper:

./gradlew :app:assembleDebug

For a conventional project, the APK is at app/build/outputs/apk/debug/app-debug.apk. Flavors and output customization change tasks and paths; inspect the actual project:

./gradlew :app:tasks --all

For a flavor named demo, look for assembleDemoDebug. A successful build produces an artifact; it doesn't mean the app was installed or launched. These task conventions are described in the Android command-line build guide.

2. Is the build on the intended device?

adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -W -n com.example.debugcli/.MainActivity

Replace the application ID and activity with your debug variant's actual values. -r replaces an installed compatible package while retaining its data. A signature mismatch needs investigation; deleting an app is not a neutral fix because it removes local data.

Alternatively, ./gradlew :app:installDebug builds and installs. Check its output to confirm the selected device or devices when several are connected. See the ADB guide.

3. Which logs belong to the running process?

After launching the app, get its current PID:

adb shell pidof -s com.example.debugcli

Suppose it prints 12345. Use that value:

adb logcat --pid=12345 -v threadtime

Stop streaming with Ctrl+C. An empty PID usually means the process isn't running or the application ID is wrong. Recheck it after a restart: a new process can have a new PID. Separate app processes need separate consideration.

A PID filter is focused, but can hide useful system-side evidence. For crash investigation, also inspect the crash buffer:

adb logcat -b crash -d -v threadtime > crash-log.txt

This dumps available crash-buffer entries, which can include other apps and older failures. Match timestamps and package/process details. It is not a complete ANR diagnosis. Inspect supported options with adb logcat --help; see the Logcat command-line reference.

4. Does the deep link actually reach the right screen?

Assume your manifest declares debugcli://product/42 as a supported route:

adb shell am start -W -a android.intent.action.VIEW -d 'debugcli://product/42' com.example.debugcli

The package restriction checks routing inside your app. Also test without that restriction to observe normal system resolution:

adb shell am start -W -a android.intent.action.VIEW -d 'debugcli://product/42'

Success means more than an activity opening: verify the destination, arguments, sign-in behavior, and Back navigation. A custom scheme doesn't prove HTTPS App Links verification. For HTTPS links, test the real domain and its verification separately. See Create deep links.

5. Does the feature handle a denied permission?

For an app that declares CAMERA and supports runtime permissions:

adb shell pm revoke com.example.debugcli android.permission.CAMERA
adb shell pm grant com.example.debugcli android.permission.CAMERA

Run these separately: revoke, exercise the denied path, then grant and exercise the granted path. Permission changes can affect the app process, so recheck its PID.

Shell grants don't test the permission dialog or every denial state. Also test the real request flow and the feature's fallback behavior. See Request runtime permissions.

6. Can you attach evidence to the issue?

adb exec-out screencap -p > debug-screen.png
adb shell screenrecord --time-limit 20 /sdcard/debug-demo.mp4
adb pull /sdcard/debug-demo.mp4 ./debug-demo.mp4

The recording command waits while recording. Pull the file after it finishes. Standard screenrecord doesn't record audio; protected content may be unavailable. See ADB screen capture and recording.

Turn the workflow into a useful bug report

Attach a short reproduction recipe with the variant, application ID, device/Android version, triggering command, expected result, and observed result. Add a timestamped log excerpt and a short recording when they explain the failure. Use test data and review logs and media before sharing them.

For your portfolio, include a DEBUGGING.md beside a sample app. Document one reproducible bug, the evidence that isolated it, and the fix. That shows the reasoning behind your tooling skills.

Which command saves you the most time when a bug refuses to reproduce from Android Studio?

Prem Singh · Lead Android Engineer · Kotlin, Jetpack Compose & Android architecture

GitHub · LinkedIn

The Compose Search Bug That Debounce Doesn't Fix

Prem Singh — Sun, 18 Oct 2026 03:23:04 +0000

A user searches for cat, then changes the query to car. For a moment, results for cats appear under the new query.

You already added debounce(300) and flatMapLatest. So why can the old request still finish?

The answer is operator placement. Debouncing reduces request frequency. It does not automatically cancel an in-flight search the instant the user edits the text.

The familiar pipeline has a timing window

Consider this simplified chain:

queries
    .debounce(300)
    .flatMapLatest { query -> searchFlow(query) }

After the user types car, the new value waits inside debounce. Until that value reaches flatMapLatest, the previous inner flow can continue. If the cat response arrives during that gap, it can still be emitted.

The Kotlin debounce reference describes suppression of rapidly followed values. The flatMapLatest reference describes cancellation when a new upstream value reaches that operator. Those are different moments.

This behavior can be acceptable when the UI deliberately keeps old results visible and labels them correctly. If you want a new query to cancel old work promptly, move the waiting period inside the switched flow.

Switch first, wait second

The following integration sketch accepts a Flow of query strings and a cancellable suspend search function. It separates waiting, loading, empty results, and failure so the UI can communicate each state clearly.

import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.buffer
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.flow.flatMapLatest
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.flow.map

data class SearchHit(val id: String, val title: String)

sealed interface SearchState {
    data object Idle : SearchState
    data class Waiting(val query: String) : SearchState
    data class Loading(val query: String) : SearchState
    data class Results(
        val query: String,
        val items: List<SearchHit>,
    ) : SearchState
    data class Failed(val query: String) : SearchState
}

@OptIn(ExperimentalCoroutinesApi::class)
fun searchStates(
    queries: Flow<String>,
    search: suspend (String) -> List<SearchHit>,
): Flow<SearchState> = queries
    .map { it.trim() }
    .distinctUntilChanged()
    .flatMapLatest { query ->
        flow<SearchState> {
            if (query.length < 2) {
                emit(SearchState.Idle)
            } else {
                emit(SearchState.Waiting(query))
                delay(300)
                emit(SearchState.Loading(query))
                try {
                    emit(SearchState.Results(query, search(query)))
                } catch (cancelled: CancellationException) {
                    throw cancelled
                } catch (_: Exception) {
                    emit(SearchState.Failed(query))
                }
            }
        }
    }
    .buffer(0)

This is a Flow-layer example, not a complete Compose app. Connect your repository and UI using dependencies compatible with your project. The experimental opt-in reflects the linked API reference; check the status for your coroutines version.

Now a new distinct, trimmed query reaches flatMapLatest before the delay. It cancels the previous inner flow, including its waiting period or cooperative in-flight request. The new flow then starts its own waiting period.

buffer(0) avoids an extra queued output buffer after the switching operator. It cannot retract a value the UI has already received, so keep the query attached to every result and render it honestly.

Keep text input responsive

Debounce the search operation, not the text field's displayed value. Typing and cursor movement should update immediately.

For state-based Compose text fields, TextFieldState owns editable text, selection, and composition. You can observe its text with snapshotFlow and feed that into the search pipeline. Preserve the text field state rather than replacing it with a fresh instance on every recomposition. The Android TextFieldState reference includes examples.

Choose the lifetime of the collector deliberately. For screen state on Android, lifecycle-aware collection is generally appropriate; a search operation should not accidentally gain a lifetime longer than its owner.

Three details worth getting right

A blank query must reach the switch. Filtering out short queries before flatMapLatest can leave an older search active when the user clears the field. This example emits Idle inside the switched flow instead.

Catch errors per request. The failure handler sits inside the inner flow. A failed request becomes a state while the outer query stream remains available for later input. A single catch after the whole pipeline can instead complete that collection after an error.

Cancellation is cooperative. A suspend function is not automatically well behaved. The repository must support cancellation and avoid blocking the calling thread. Cancelling a client request also doesn't guarantee the server stopped processing it. Never swallow CancellationException as an ordinary search error.

What about retrying the same query?

distinctUntilChanged intentionally suppresses equal adjacent queries. Assigning the same string again won't implement retry.

Model retry as a separate action. For example, include an attempt counter in a request model and increment it on retry, so the request stream sees a new value even when the query is unchanged. Decide whether explicit retries should bypass the typing delay.

Test the timing, not just the final list

Use a fake search implementation and virtual time to verify these scenarios:

Scenario	Expected behavior
Rapid typing	Only the settled query starts a search
Edit during a request	Previous cooperative request is cancelled when the new query reaches the switch
Clear the field	State becomes Idle; previous work is cancelled
Request fails, then query changes	A new search can still run
Retry unchanged text	Explicit retry creates another attempt

A small demo showing the query, current state, and cancellation logs makes this a useful portfolio feature. It demonstrates an engineering decision that a polished screenshot alone cannot show.

The next time you review a search pipeline, ask: does cancellation happen when the user changes intent, or only after the debounce window?

Prem Singh · Lead Android Engineer · Kotlin, Jetpack Compose & Android architecture

GitHub · LinkedIn

Your Compose Screen Is Gone. Why Is Your Flow Still Running?

Prem Singh — Sun, 18 Oct 2026 03:10:19 +0000

Press Home on an Android app. The screen disappears, but that doesn't automatically mean every coroutine feeding it has stopped.

For a search screen, live dashboard, or AI response view, this distinction matters. A UI collector and the producer behind it have separate lifetimes. Reviewing only one can leave unnecessary work running—or stop work that the product actually needs to finish.

Here's a small pattern worth understanding before adding more architecture to a Compose screen.

1. Collect screen state with the Android lifecycle

For an Android Compose route backed by a ViewModel, use lifecycle-aware collection:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.lifecycle.compose.collectAsStateWithLifecycle

@Composable
fun FeedRoute(viewModel: FeedViewModel) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()
    FeedScreen(state)
}

FeedScreen is your rendering composable; FeedViewModel is supplied by your app's normal ViewModel creation mechanism. Add androidx.lifecycle:lifecycle-runtime-compose using a version aligned with your project's Lifecycle dependencies.

By default, collection runs when the lifecycle is at least STARTED. It stops below that state and starts again when the lifecycle becomes active. This is different from ordinary collectAsState(), whose collection follows the composition rather than applying this lifecycle threshold. See the Android Compose state guide.

That fixes the consumer side. Now look upstream.

2. Give the upstream an explicit sharing policy

Here is an integration sketch for a repository that observes feed items. It assumes a cold Flow whose observation work is cancelled when its collector is cancelled. Adapt the model and repository to your app.

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.catch
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.stateIn

data class FeedItem(val id: String, val title: String)

sealed interface FeedUiState {
    data object Loading : FeedUiState
    data class Content(val items: List<FeedItem>) : FeedUiState
    data object Error : FeedUiState
}

interface FeedRepository {
    fun observeItems(): Flow<List<FeedItem>>
}

class FeedViewModel(repository: FeedRepository) : ViewModel() {
    val uiState: StateFlow<FeedUiState> = repository.observeItems()
        .map<List<FeedItem>, FeedUiState> { items ->
            FeedUiState.Content(items)
        }
        .catch { cause ->
            if (cause is CancellationException) throw cause
            emit(FeedUiState.Error)
        }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(
                stopTimeoutMillis = 5_000,
            ),
            initialValue = FeedUiState.Loading,
        )
}

The explicit map result type allows both Content and Error to flow through the same pipeline. The cancellation guard makes the intended behavior clear: cancelling observation should not become a visible failure.

These are focused integration snippets, not a complete sample app. The repository, UI rendering, and dependency setup remain application-specific.

3. Read the timeline, not just the API name

With the policy above, the expected sequence is:

UI starts collecting       -> upstream observation starts
last subscriber disappears -> five-second grace period begins
subscriber returns early   -> existing observation continues
no subscriber after 5s     -> sharing cancels upstream collection
subscriber returns later   -> upstream collection starts again

The grace period can bridge short subscriber gaps such as configuration changes. Five seconds is a choice, not a universal performance rule.

The default replay expiration retains the last value: stopping the upstream doesn't automatically put uiState back into Loading. Returning users can see cached content while observation restarts. Read the Kotlin WhileSubscribed reference before changing cache behavior.

4. Know what this pattern does not stop

WhileSubscribed controls this sharing coroutine. It doesn't cancel every job in the ViewModel or shut down an independently running hot producer.

For example, this job has a different owner:

init {
    viewModelScope.launch {
        repository.refreshOnce()
    }
}

Here refreshOnce() represents an application-specific suspend function. Its job can continue after the UI stops collecting because it was launched separately in viewModelScope.

This can be intentional. An explicit user action and an observational feed don't always need the same lifetime. Decide whether an operation should stop when the screen becomes inactive, survive a navigation change, or require durable execution. Then choose its owner.

5. Handle failures and retry deliberately

The catch above turns a failure into an error state, but it does not continuously retry. Once that upstream attempt completes, a retry action needs an explicit strategy, such as a refresh trigger that starts a new observation, or a bounded retryWhen policy before catch for suitable transient failures.

Don't rely on backgrounding and reopening the app as the user's retry mechanism. Also consider retaining existing content alongside a refresh error when that serves the screen better.

A useful code review exercise

For the next Flow-backed screen you review, trace four things:

Which lifecycle controls the UI collector?
Which scope owns the producer?
Does cancellation actually reach the underlying work?
What happens after failure, and who triggers another attempt?

For a portfolio demo, instrument a fake cold Flow with start and cancellation logs, then record navigating away and returning before and after the timeout. Show the logs beside the screen recording. That demonstrates the behavior far more clearly than a screenshot of an API call.

The key design decision is ownership: the screen's visibility, the observer's lifetime, and the operation's lifetime should each be intentional.

What do you usually find in reviews: missing lifecycle-aware collection, or upstream work with an unexpected lifetime?

Prem Singh · Lead Android Engineer · Kotlin, Jetpack Compose & Android architecture

GitHub · LinkedIn