As a mobile engineer, you’ve probably seen terms like SHA-1 and SHA-256 pop up everywhere—in your IDE warnings, API documentation, and app signing configurations. But what do they actually mean, and why should you care?

Think of a cryptographic hash function as a digital fingerprint generator. You can feed it any data — an entire APK, a user’s password, a simple string — and it will spit out a unique, fixed-size string of characters called a hash.

This article will break down what these hashes are, why the old standard (SHA-1) is dangerous, why SHA-256 is the current champ, and what the fast and exciting future looks like.

The 3 Golden Rules of Secure Hashes

A secure hash function is like a magical, one-way blender. You can put ingredients in and get a smoothie, but you can never turn that smoothie back into the original ingredients. This “magic” relies on three core security properties:

1. Pre-image Resistance (The One-Way Street): Given a hash, you can’t figure out the original input. This is why we store password hashes instead of the passwords themselves. If a database leaks, attackers get a list of hashes, not the actual passwords.
2. Second-Preimage Resistance (The No-Imposter Rule): If you have a file and its hash, nobody can create a different file that produces the same hash. This is crucial for verifying that an app update you’ve downloaded hasn’t been tampered with.
3. Collision Resistance (The No-Evil-Twins Rule): This is the big one. Nobody should be able to find any two different inputs that create the same hash. A failure here is catastrophic, as it means a hacker could craft a malicious file that has the same “fingerprint” as a legitimate one.

The Story of SHA-1: The Fallen Hero

For years, SHA-1 was the king. It was used for everything: signing apps, securing websites (SSL/TLS certificates), and verifying file integrity. It produces a 160-bit hash.

So, what went wrong? In short, it became too predictable.

The final nail in the coffin came in 2017 with the SHAttered attack. Researchers from Google and CWI Amsterdam proved it was practical to break SHA-1's collision resistance. They created two completely different PDF files that had the exact same SHA-1 hash.

Why this is terrifying for a mobile dev: Imagine if a hacker could create a malicious APK that has the same digital fingerprint as your legitimate app update. They could upload it somewhere, and systems that rely on SHA-1 for verification would see it as authentic. This is why your IDE screams at you if you use SHA-1 in a security context. It’s broken. Don't use it.

SHA-256: The Current, Secure Champion

Enter SHA-256. It's part of the SHA-2 family and is the modern standard for secure hashing. It produces a larger 256-bit hash and is structurally much stronger than SHA-1.

Here’s a simple breakdown of why it’s better:

FeatureSHA-1 (The Old Way)SHA-256 (The Modern Way)Fingerprint Size160-bit256-bitInternal "Blender"Simple, linear recipe.Complex, non-linear recipe.

Where you see SHA-256 today:

• App Signing: Modern Android app signing schemes (like v2, v3, and v4) rely on the security of SHA-256 to ensure the integrity of your APK.
• Blockchain: Bitcoin's famous proof-of-work algorithm uses a double SHA-256 hash. Its security is a testament to the algorithm's robustness.
• Networking Security: When you use libraries like OkHttp to communicate with servers, the TLS certificates that secure your connection are signed using strong hashes like SHA-256.

The Future: Faster Hashes and Quantum Threats

The world of cryptography never stands still. Here’s a look at what’s next.

The Need for Speed: Meet BLAKE3

While SHA-256 is secure, it's not the fastest. BLAKE3 is a modern hash function designed for insane performance.

Its secret weapon? Parallelism.

Think of it this way: Hashing a large file with SHA-256 is like one person reading a very long book from start to finish. BLAKE3 is like tearing the book into chapters and giving one to each of your friends to read at the same time. It's massively faster, especially on the multi-core CPUs in modern devices and servers.

For mobile devs, this could mean faster integrity checks for large game assets, quicker processing of large media files, and more.

The Sci-Fi Threat: Quantum Computers

You may have heard that quantum computers will "break" cryptography. For hashing, the threat comes from Grover's algorithm, a quantum search algorithm that makes finding a pre-image (guessing the input from the hash) easier.

• The Impact: It effectively halves the security level of a hash function. For SHA-256, its 256-bit security drops to a 128-bit level.
• Should you panic? No. A 128-bit security level is still considered computationally impossible to break for the foreseeable future. So, while SHA-256 is weakened by quantum computers, it isn't broken.

The crypto community is already preparing for this future by recommending SHA-512 for long-term security (which would have a 256-bit post-quantum security level) and developing entirely new quantum-resistant standards.

Key Takeaways for Mobile Engineers

1. Never Use SHA-1 for Security. It's broken. Listen to your IDE warnings. The same goes for MD5.
2. SHA-256 is Your Go-To Standard. It's secure, trusted, and the industry standard for everything from app signing to data integrity.
3. For High Performance, Keep an Eye on BLAKE3. If your app deals with hashing large files and speed is critical, BLAKE3 is the future.
4. Don't Lose Sleep Over Quantum Computers (Yet). SHA-256 is still safe for now, and the industry is already building the next generation of defenses.

Understanding which hash function to use is a small but crucial part of building secure and reliable applications. By choosing modern, robust algorithms, you're helping to protect your app, your company, and your users.

Follow to stay connected and get timely updates. 🙌🏻

What Every Android Engineer Needs to Know About SHA-1, SHA-256, and Beyond was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

When building search into an Android application — whether querying an offline-first inbox, notes catalog, documentation cache, or e-commerce catalog — almost every developer starts with the same query:

SELECT * FROM mails 
WHERE subject LIKE '%' || :query || '%' 
   OR body LIKE '%' || :query || '%'

It is intuitive, requires zero schema alterations, and works out-of-the-box. During early development, when your local database contains 25 dummy rows, search queries return instantly. Tests pass, the UI feels snappy, and the feature gets shipped.

Then reality strikes.

As users accumulate months of multiline emails, notes, or cached payloads (climbing from hundreds to thousands of records), complaints begin rolling in:

• Keystroke lag when typing in search fields.
• Skipped frames and main-thread micro-stutters.
• Noticeable battery drain during heavy search workflows.

Why does an operation that felt blazing fast in development fall apart under real-world volume? To understand this, we have to look under the hood of SQLite’s query planner.

Why SQL LIKE Fails at Scale

In relational databases, developers rely on indices (B-Trees) to keep lookups at O(log N) time. If you query:

WHERE sender LIKE 'alice%'

SQLite can utilize a standard B-Tree index on sender because it knows the prefix.

However, users rarely search by prefix alone. Real-world full-text search requires substring matching: finding a word anywhere within a subject or paragraph. This forces the query into a leading wildcard:

WHERE body LIKE '%architecture%'

WARNING: The moment a query contains a leading wildcard (%query%), standard B-Tree indices are completely bypassed. SQLite is forced to execute a sequential full table scan O(N).

In a full table scan:

1. SQLite reads every single row off the storage layer into memory.
2. The query engine steps through every single byte of text sequentially, comparing character by character looking for the target substring.
3. If an email body contains 1,500 words and you have 2,000 emails, SQLite inspects up to 3,000,000 words byte-by-byte for every single keystroke!

Furthermore, standard SQL LIKE is "dumb":

• No tokenization: It doesn’t know what a word boundary is. Searching for "cat" will inadvertently match "catalog", "scatter", and "vacation".
• No stemming: Searching for "optimize" will miss "optimizing", "optimizer", or "optimized".
• No relevance ranking: Results are unweighted; a match in the title has the same weight as a match tucked away in paragraph four.

This is where SQLite’s FTS4 (Full Text Search 4) engine changes the game.

The Solution: How FTS4 and Inverted Indices Work

SQLite includes dedicated full-text search extensions (FTS3/FTS4 and FTS5). In Android's Room persistence library, this is natively supported via the @Fts4 and @Fts3 annotations.

The Inverted Index: From O(N) to O(1)

Instead of scanning rows at query time, FTS4 does the heavy lifting at insert time.

When a text column is indexed by FTS4, a tokenizer breaks the text down into individual words (tokens), normalizes their case, strips punctuation, and builds an Inverted Index.

An inverted index is essentially a word-to-document dictionary:

+--------------+-----------------------+
| Token        | DocIDs (Posting List) |
+--------------+-----------------------+
| architecture | [1, 14, 108, 492]     |
| benchmark    | [1, 7, 22, 108, 305]  |
| database     | [1, 4, 18, 92, 108]   |
| security     | [2, 6, 11, 45, 99]    |
+--------------+-----------------------+

When you issue a search query like MATCH 'benchmark*', FTS4:

1. Tokenizes the search string.
2. Performs an instantaneous lookup in the token dictionary.
3. Retrieves the exact list of docid numbers containing the word.
4. Returns the records without scanning a single byte of irrelevant text.

Whether you have 100 rows or 100,000 rows, lookups happen in fractions of a millisecond.

Implementation in Android Room

A common misconception is that using FTS requires duplicating your data and doubling your database size. With Room’s contentEntity pattern, this is completely avoided.

Let’s look at the production implementation from our Mail Showcase application.

First, create your base table containing all raw fields. This remains your single source of truth:

// MailEntity.kt
import androidx.room.Entity
import androidx.room.PrimaryKey

@Entity(tableName = "mails")
data class MailEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val sender: String,
    val recipient: String,
    val subject: String,
    val body: String,
    val timestamp: Long = System.currentTimeMillis()
)

Next, define the virtual FTS entity. By declaring contentEntity = MailEntity::class, Room instructs SQLite to use an External Content Table.

The FTS table maintains only the index structures and token postings. The text itself is fetched on-demand from the base mails table, eliminating storage duplication:

import androidx.room.Entity
import androidx.room.Fts4

@Entity(tableName = "mails_fts")
@Fts4(contentEntity = MailEntity::class)
data class MailFtsEntity(
    val sender: String,
    val subject: String,
    val body: String
)

TIP : Under the hood, Room automatically creates SQLite database triggers (AFTER INSERT, AFTER UPDATE, AFTER DELETE) on the mails table. Whenever you insert or update a MailEntity, the mails_fts index updates automatically!

Register both classes in your @Database declaration:

@Database(
    entities = [MailEntity::class, MailFtsEntity::class],
    version = 1,
    exportSchema = false
)
abstract class MailDatabase : RoomDatabase() {
    abstract fun mailDao(): MailDao
}

Now we can compare both queries in our MailDao.

Notice how the FTS query joins mails.id against mails_fts.docid:

@Dao
interface MailDao {

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertMails(mails: List<MailEntity>): List<Long>

    /**
     * Standard SQL LIKE operator search.
     * Triggers an O(N) sequential scan across every row.
     */
    @Query(
        """
        SELECT * FROM mails
        WHERE subject LIKE '%' || :query || '%'
           OR body LIKE '%' || :query || '%'
           OR sender LIKE '%' || :query || '%'
        ORDER BY timestamp DESC
        LIMIT :limit
        """
    )
    suspend fun searchMailsLike(query: String, limit: Int = 200): List<MailEntity>

    /**
     * SQLite FTS4 (Full Text Search) MATCH query.
     * Uses inverted index token lookups.
     */
    @Query(
        """
        SELECT mails.* FROM mails
        JOIN mails_fts ON mails.id = mails_fts.docid
        WHERE mails_fts MATCH :query
        ORDER BY mails.timestamp DESC
        LIMIT :limit
        """
    )
    suspend fun searchMailsFts(query: String, limit: Int = 200): List<MailEntity>
}

To provide an “as-you-type” search experience, sanitize the input and append a wildcard * to the tokens so that typing "arch" matches "architecture":

private fun sanitizeFtsQuery(query: String): String {
    val sanitized = query.replace("\"", "").replace("'", "").trim()
    val tokens = sanitized.split("\\s+".toRegex()).filter { it.isNotEmpty() }
    if (tokens.isEmpty()) return ""

    // Appending '*' enables fast token prefix matching in FTS
    return tokens.joinToString(" ") { "$it*" }
}

To measure real-world performance, we built a benchmarking suite into the showcase app that measures database execution duration down to the microsecond (measureNanoTime) on identical datasets.

We populated the database with multiline emails and measured search latency across dataset scales:

+--------------+-------------------------+-------------------------+----------------+
| Dataset      | SQL LIKE Latency        | Room @Fts4 MATCH        | Speedup Factor |
+--------------+-------------------------+-------------------------+----------------+
| 100 mails    |  2.840 ms (39 matches)  |  1.800 ms (39 matches)  | 1.6x faster    |
| 500 mails    |  8.114 ms (179 matches) |  3.892 ms (179 matches) | 2.1x faster    |
| 2,000 mails  | 30.181 ms (200 matches) | 13.071 ms (200 matches) | 2.3x faster    |
| 5,000 mails  | 63.762 ms (200 matches) |  6.811 ms (200 matches) | 9.4x faster    |
+--------------+-------------------------+-------------------------+----------------+

Query Execution Time vs Dataset Size
Latency (ms)
  70 ┼                                                  ● SQL LIKE (63.8 ms)
  60 ┼                                                 
  50 ┼                                                
  40 ┼                                              
  30 ┼                                  ● (30.2 ms) 
  20 ┼                                              
  10 ┼                    ● (8.1 ms)             ● FTS4 (6.8 ms)
   0 ┼───● (2.8 ms)───────● (3.9 ms)────● (13.1 ms)──────
     └──────┬─────────────────┬──────────────┬──────────────┬────────
          100               500           2,000          5,000
                                 Email Records

Key Observations:

1. The 16ms Frame Budget Barrier: At 2,000 emails, SQL LIKE takes ~30.18 ms, breaching the ~16.6 ms frame target for 60Hz displays (and ~8.3 ms for 120Hz displays). At 5,000 emails (~63.76 ms), executing LIKE on or near the UI thread causes dropped frames and noticeable UI stutter.
2. Diverging Performance at Scale: While FTS4 offers a steady 1.6x–2.3x improvement on smaller to medium datasets, its advantage explodes at 5,000 records, executing 9.4x faster than LIKE (~6.81 ms vs. ~63.76 ms).
3. Prefix Support: FTS4 handles arch* queries instantly because token prefixes are traversed directly in the index structure.

When to Use Which

| Feature                   | SQL LIKE '%query%'                | Room @Fts4 (MATCH)                           |
+---------------------------+-----------------------------------+----------------------------------------------+
| Algorithmic Complexity    | O(N) Sequential full table scan   | O(1) / Sublinear Inverted index lookup       |
| Execution Time at Scale   | Degrades linearly with row count  | Remains consistently in low single-digit ms  |
| Word Boundary Awareness   | No (matches substrings blindly)   | Yes (tokenized at word boundaries)           |
| Stemming Support          | No                                | Yes (Porter stemmer available)               |
| Prefix Matching           | Wildcards break B-Tree index      | Native (MATCH 'token*')                      |
| Storage Impact            | Zero overhead                     | Minimal index metadata (via contentEntity)   |
| Insert Overhead           | Minimal                           | Slight cost during insert to update index    |
+---------------------------+-----------------------------------+----------------------------------------------+

Conclusion

SQL LIKE is a wonderful tool for prototyping or querying discrete code columns (like status codes or short identifiers). But the moment your application handles human text—messages, documents, notes, product catalogs—relying on LIKE '%...%' is a ticking performance bottleneck.

By incorporating Room’s @Fts4 with the contentEntity pattern:

• You retain clean, relational entities as your source of truth.
• You gain high-performance inverted index lookups that scale effortlessly into tens of thousands of items.
• Your UI remains silky smooth, respecting the user’s frame budget and battery life.

If your Android app has a search bar querying text fields, don’t wait for your dataset to grow in production. Migrate to Room FTS and deliver an instant search experience your users will love.

References

Fts4 | API reference | Android Developers

LinkedIn

Youtube

Love you all.

Stay tune for upcoming blogs.

Take care.

Scaling Android Search: Room @Fts4 vs SQL LIKE was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Part 3 of my KMP series: how Android product flavors let the free version of my app leave the sign-in, sync and payment code out of the build

List: Building an Exam Prep App with Kotlin Multiplatform | Curated by Avik Sharma Chowdhury | Medium

In Part 1, I shared how my plan changed after completing the closed testing with MVP. I decided to launch the app for free and keep the paid features (sign-in, cloud sync and a premium subscription) ready for later. In Part 2, I walked through how the project is organized.

This part is about how one codebase builds both versions: a free app with only the core features, and a full app with everything. I’ll cover product flavors, how the free app leaves the premium features out, and how the shared code works with either version without knowing which one it’s in.

One note before we start: product flavors are an Android feature, and everything in this part is about the Android app. On iOS, I plan to release the full version, so the iOS code simply includes all the features.

Why Two Builds?

My first attempt was introducing a feature flag that hid the premium features. The free version still included the Auth and Payment SDKs and still asked for the billing permission, even though no one can buy anything.

I wanted the free app to contain only what it uses. That meant building two different apps from the same code.

Product Flavors

A product flavor is Android’s way of building different versions of an app from one codebase. You define flavors in Gradle, and each flavor can have its own code, resources and dependencies.

The flavors are grouped into two dimensions:

• environment (dev / prod): a development version and a release version. The dev build has a different app ID, so both can be installed on the same phone.
• distribution (free / full): which features the app includes. The free flavor has only the core features, and full flavor includes sign-in, sync and payments.

Gradle combines them into variants such as prodFreeRelease, which is the app on Google Play, and devFullDebug, which I use to work on the premium features.

Leaving Auth and Payment Code Out

The sign-in and sync code lives in an auth module, and the payment code lives in a payment module. Both are added only to the full flavor:

dependencies {
    // Only the full build includes sign-in, sync and payments
    "fullImplementation"(project(":libs:auth"))
    "fullImplementation"(project(":libs:payment"))
}

fullImplementation means only include this in builds of the full flavor. The free app on Google Play doesn’t contain the sign-in, sync or payment code, or the SDKs behind them.
The billing permission works the same way. It’s declared in a small manifest file inside the androidFull folder, so only the full app asks for it.

Hiding the SDKs Behind Interfaces

The shared code never uses the auth or payment modules directly. It only uses interfaces. These interfaces live in a small module called domain-api. This module holds only interfaces and simple data classes, with no SDKs:

The shared code depends on these interfaces. The auth and payment modules implement them with Supabase and RevenueCat. The free build has its own simple versions that do nothing.

Picking the Right Code at Startup

Something still has to decide which versions of the interfaces the app uses. This is where the flavor source sets come in. Each flavor has its own folder, androidFree and androidFull, and only one of them is compiled into a build.

In commonMain, there's a small interface for whatever cloud setup the build has:

interface CloudBootstrap {
    fun modules(): List<Module>
    fun onKoinStarted(koin: Koin) {}
}

Each flavor folder defines a value with the same name, cloudBootStrap. In androidFree, it loads freeCloudModule. This module has no-op (no operation) versions of the sign-in, sync and payment interfaces.

val cloudBootstrap: CloudBootstrap = object : CloudBootstrap {
    override fun modules(): List<Module> = listOf(freeCloudModule)
}

The free version doesn’t override onKoinStarted. The interface already gives it an empty default, so in the free build that call does nothing.
In androidFull, it loads the real modules and sets up payments once Koin has started:

The app’s startup code in androidMain uses cloudBootstrap without knowing which one it got:

The free build’s module provides the same interfaces with fakes and no-ops.

A Safety Net for the Free Build

The free build should never include the auth and payment code. One wrong line in a Gradle file could bring it back, and the app would still build without any error. To catch that, I added a check to CI.

On every pull request, GitHub Actions lists every library in the free release build and fails if one of the full-only SDKs shows up:

Lessons Learned

• A feature flag hides a feature. A flavor-only dependency removes it. If you don’t want code in an app, keep it out of the build.
• Keep third-party types out of your interfaces. Convert them into your own types inside the module that uses the library.
• Give shared code interfaces, and let each build choose the implementation. The shared code stays the same for both versions.
• Add a CI check for every rule you care about. It’s easy to break a structure rule without noticing.

Wrapping Up

Building this app taught me more about Kotlin Multiplatform than any tutorial did. Most of the lessons came from real problems, like reorganizing the project as it grew, keeping SDKs out of the shared code, and fixing an iOS build that broke without warning. I hope learning about these pitfalls saves you some time on your own project.

I might write more about the app later, like offline sync or testing in-app purchases. If you’d like to see that, follow me here on Medium. And if you’re working on a KMP app yourself, I’d love to hear what you’ve learned in the comments.

Thanks for reading! If you’re preparing for the “Leben in Deutschland” test, you can try the app on Google Play.

How I Built Free and Full Build Flavors for Android in my KMP codebase was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

TL;DR

• The most important local data in our app now lives in Jetpack DataStore, replacing SharedPreferences.
• We measured the impact with an isolated benchmark: no measurable runtime cost. Cold start, hot start, CPU, and memory all stay within normal run-to-run variation.
• Migrating existing users’ data to DataStore runs once and finishes in tens of milliseconds, on a background thread.
• In the same release, the app as a whole shows its first screen 0.7 seconds faster than the previous release on a Samsung Galaxy A55. DataStore did not stand in the way of that.

Why we left SharedPreferences

SharedPreferences has been part of Android since API 1. It is simple and good enough for many cases. But in an app as large as ours, its limits started to show.

1. The API is synchronous, and it is often called from the main thread.
The first read of a SharedPreferences file blocks the calling thread until the whole file is loaded from disk. If that thread is the main thread, the UI waits too.

2. apply() is not fully asynchronous.
apply() looks like a background write. But Android waits for every pending apply() to finish when an Activity stops or a Service finishes. On a device with slow storage, that wait can turn into an ANR. commit() is worse, because it blocks explicitly.

3. Write failures are invisible.
apply() never tells you whether the data was actually saved. If it fails, the app never finds out.

4. There is no convenient reactive way to observe changes.
All you get is a listener, which leaks easily and does not fit with coroutines or Flow.

5. Types are not enforced.
Storing an Int and reading it back as a Long only surfaces at runtime, as a ClassCastException.

Jetpack DataStore was designed to address all of this:

Benchmark results

The question we heard most before the release: “If the storage moves to DataStore, won’t the app get slower?”

We answered it with several measurements.

1. Isolated benchmark: what does DataStore cost on its own?

Our release contained many changes besides DataStore. To keep DataStore’s effect from getting mixed in, we built three APKs:

• The previous release.
• The new release without DataStore, meaning every change in the release except the migration.
• The new release with DataStore, meaning the build we actually shipped.

The difference between the second and third builds is the cost of DataStore and nothing else. All three were measured back to back in a single 24-minute session on a Xiaomi Redmi Note 9 Pro (Snapdragon 720G, 6 GB RAM), 10 cold starts per build, with normal thermal status on all 30 runs.

DataStore adds no measurable runtime cost. Every startup, CPU, and memory difference is smaller than the run-to-run variation within the same build. Screens A and B are the two screens users open most. The only consistent change actually goes the right way: CPU on screen B at idle dropped 2.6 points, and that drop showed up in two separate measurement sessions.

2. Updating from an old version on a low-end device

The hardest scenario for the migration is an existing user updating on an inexpensive device, because that is where the data migration actually runs. We measured it with Perfetto on a Samsung Galaxy A15, 10 iterations per build, with old data already in place before the update.

All 10 cold start iterations and all 10 warm start iterations were faster on the new APK. That includes the first iteration, the only launch that runs the data migration: 7.04 seconds, no slower than the average.

The two APKs differ by more than the storage layer, so this speed-up belongs to the release as a whole. What this measurement proves is the thing we worried about most beforehand: the data migration does not make existing users wait longer.

3. How long does the migration itself take?

We record the migration’s duration through telemetry. On our test device:

The migration runs on a background thread and finishes in milliseconds, so users never feel a wait.

4. The release as a whole

On a Samsung Galaxy A55, 10 runs per metric:

Even the slowest run of the new release was faster than the fastest run of the previous one. This is the work of the whole team on that release, not DataStore alone. But it answers the original concern quite firmly: replacing the storage foundation did not stop the app from getting faster.

What these numbers taught us

Measure the change on its own. Our first measurement compared the old release with the new one and found a CPU increase on one of the screens. Once we built a version without DataStore, it turned out the increase came from other changes in the same release, and DataStore actually brought it down. Without that comparison build, we would have blamed the wrong component.

Measure in one session. Measurements taken hours or days apart produced differences that did not hold up when repeated. Network conditions, server-driven content, and device temperature all change in between. Measuring every build back to back in one session removes most of that noise.

Report the range, not just the average. Memory on the same screen, for the same build, can move by more than 30 MB between samples. A 14 MB difference in the average between two builds means nothing against variation that large.

Build in telemetry from the start. Migration duration and write failures are sent as events. The question “how long does the migration take on users’ devices?” can be answered from production data instead of guesswork.

Closing

A storage migration is rarely visible to users, and that is exactly how it should be. Its success is measured by what doesn’t happen: no lost data, no interrupted user sessions, no app that got slower.

These numbers give us the confidence to keep going: moving more data to DataStore does not have to be traded against performance.

Thank you to everyone involved: those who reviewed the plan again and again, those who tested the update scenarios one by one, and those who ran the benchmarks until the numbers could be trusted.

All numbers in this article come from internal measurements on physical devices. Results on other devices may differ, especially in absolute values.

Moving Local Storage to Jetpack DataStore Without Paying a Cent in Performance was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

The last article in this series ended with a vendor fix. Its SDK had declared kotlin-stdlib 2.3.0, which AGP consistent resolution carried onto our modules’ classpaths. Detekt’s type-resolving analysis uses an embedded Kotlin compiler. In this incident, that older compiler could not handle the newer dependency metadata correctly and reported 42 phantom UnsafeCast findings. They disappeared with a compatible analysis classpath. The vendor removed the stdlib declarations, but the nightly stayed red.

Over the next month, I traced the remaining dependency path and audited our own SDKs. We had been publishing the same kind of dependency. Fixing our pipeline took several attempts, including one that passed every publication check and still broke a consumer’s build.

One warning before we start. The comfortable version of this story is a line graph: incident, root cause, fix, green. The real version is a staircase where every landing reveals another flight. The vendor’s fix was correct and incomplete. Our first fix was correct and wrong. The second was correct and half-blind. The third held, and then a review pass found a bug in the fix itself. I would edit that sequence out as implausible, if it had not happened to me.

Verifying a fix you did not write

The calls SDK family came back clean at the end of August. I downloaded fresh POMs and module descriptors straight from the registry and parsed them: zero stdlib declarations. I wanted to check the published files, not whatever Gradle had cached locally.

The nightly cron disagreed with my optimism. Same 21 modules, same rule, 43 findings now, one more than the original incident. So before hunting anything new, I needed one fact: are these 43 phantoms, or did something real sneak in behind the noise?

I made a fresh checkout of develop, cherry-picked the workaround from part one that changes the stdlib only inside detekt tasks, and ran all 21 failing modules without caches. All 21 passed in under four minutes. The findings disappeared with a readable analysis classpath, pointing back to the dependency graph.

Next: who was still asking for 2.3.0? The dependency insight on a failing module still showed the same two selection reasons:

org.jetbrains.kotlin:kotlin-stdlib:2.3.0
  Selection reasons:
      - By constraint: version resolved in configuration
        'debugRuntimeClasspath' by consistent resolution
      - By conflict resolution: between versions 2.3.0 and 2.2.10

Somebody in the graph was still declaring it. Finding out who involved two traps worth passing on.

Trap one: the guilty POM was not in the local cache. Gradle’s files store keeps a .pom next to most artifacts, but the local files cache contained only its AAR, and the descriptor lived in the binary metadata cache. Grepping the cache for a version string came up empty and proved nothing. Absence of a pin in your cache is not absence of a pin. The cache is a derived, prunable, format-private store, not a registry mirror.

Scanning the binary descriptor files for strings surfaced an API client, its json and http siblings, and their logging library. They came from one repository and toolchain. My first audit had stopped at the first affected SDK family; another family still requested the same version.

The second trap took more digging. The API client’s registry lastModified timestamp was about a month later than the commit that adopted that version in our app. Earlier CI logs were green; the findings started after the timestamp’s date. My best explanation was a same-version republish with a newer toolchain’s stdlib declaration. I had not kept the earlier artifact, so I could not compare the two versions’ bytes. The timing was observed; the republish mechanism was a reconstruction.

This is why release artifacts need new version numbers when their contents change. Reusing a number can leave some consumers on cached content while others download the replacement.

The mirror

The sibling team’s first counterargument was not about their pins. It was about ours. Their claim was simple: your published SDKs pin the stdlib too, you are just lucky your pin sits close to your hosts’ Kotlin.

They were right. Our SDK declared stdlib 2.2.10, which matched our app’s version and therefore caused no uplift there. A consumer on an older Kotlin version could see a different result. We needed to check that case too.

That argument deserved a number, so I audited the POMs in our registry. Here is a standalone Python 3 scanner for POMs you have already downloaded. Save it as scan_poms.py and run python3 scan_poms.py ./downloaded-poms; it uses only the standard library. It distinguishes direct declarations from dependency-management entries and handles XML namespaces:

This inspects declarations, not effective Maven models or resolved Gradle graphs: it prints property references verbatim, does not resolve parent POMs or imported BOMs, and does not inspect profiles, plugin dependencies, or .module files. A MANAGED entry is not itself a dependency edge. The directory contents define the sample; the script does not select the latest version of each artifact or compute a registry-wide percentage.

The original registry audit found that roughly half of several hundred published artifacts declared the stdlib, spread across toolchain generations going back years. The audit lesson from part one had been aimed at vendors. It should have been aimed at a mirror.

The useful discovery was that these artifacts shared a monorepo and publication pipeline. We could fix the metadata generation in one place instead of asking each SDK consumer to work around it.

The platform team had already tried disabling Kotlin’s default stdlib dependency. In this build, that had not been enough. I started by finding out what kept adding it.

The fix that worked and was still wrong

Parcelize-related runtime dependencies still introduced paths to stdlib with the default dependency flag off. Our SDK modules use @Parcelize heavily because parcelable models are part of their API.

The first fix changed the convention plugin for publishable modules. It removed stdlib from api and implementation, then added it as compileOnly and to the test configurations that needed it. In our build, a withDependencies callback let the removal run after the Kotlin and Parcelize plugins had added their dependencies. That ordering worked in the tested setup, but became a concern in review.

The first version passed our local checks:

• Generated POM and .module for a parcelize-heavy SDK module and a plain one: zero stdlib declarations, all other dependencies intact. Both formats, same generation run, because comparing artifacts from different generation tasks once sent me chasing a bug in a vendored generator that did not exist. The phantom hunter caught his own phantom that evening.
• Compilation of the touched modules came back UP-TO-DATE versus the unfixed build. That is a useful signal, and I will come back to what it does and does not prove.
• Unit tests of the SDK modules, which need the stdlib at compile and runtime of the tests, to prove the test wiring survived the strip.
• A full app assemble, an APK size sanity check, and a smoke run of all three shipped apps on an emulator, zero crashes.
• A detekt pass over the touched modules, because irony is a load-bearing wall in this story: the pre-commit hook of the very static analysis we kept alive through part one blocked the first commit of this fix, a cyclomatic complexity complaint against the function that saved it. The hook was right. The function got smaller.

Review raised a problem with the approach: we were changing SDK build configurations to fix published metadata. The callback ordering also depended on another plugin’s behavior, which could change on upgrade. The suggested fix was to move the policy into publication generation.

I argued, then I checked the callback ordering claim, then I stopped arguing. The fix moved.

The publication layer

The revised implementation had three parts:

• A policy object: the single list of coordinates a published artifact may not declare as a dependency, the stdlib and its jdk7/jdk8 companions. One source of truth, plain data, no logic to drift.
• A filter in the POM assembly: the publication utility walks the generated dependency nodes, removes the forbidden ones, and on the runtime edges that can carry the stdlib transitively adds an explicit exclusion. The Gradle API for this is the withXml hook on the Maven publication, and the operation is idempotent, which matters later.
• The module metadata side. This is the delicate part. Our pipeline builds .module files through a vendored fork of Gradle’s own metadata generator, and the rule in review was: minimal diff in someone else’s clone, because that fork is already hard to update. So the builder consults the same policy while assembling its dependency lists: coordinates to drop, exclusion rules to add. A handful of lines in one file, no signatures changed.

The POM half of that, extracted from the implementation and trimmed to the parts that carry the decision (Node is groovy.util.Node, the object withXml hands you). This is the final version, including the exclusions the consumer experiments below discovered; the first iteration only removed direct declarations:

And the hook, which is the public Gradle API for exactly this, three lines in the publication factory:

The helper matters for both types and namespaces. Node.get() returns Object, so Kotlin needs the list cast. It also looks up the local element name in the namespace-aware nodes Gradle supplies: comparing node.name() directly to a string misses QName names and can silently leave the POM unchanged. A POM without a dependencies section passes through quietly instead of throwing.

The .module side has no equivalent public hook in our build: our descriptors come from a vendored fork, and the same policy object feeds a skip-list inside it. That is a fact about our pipeline, not an API recommendation. If you publish with stock Gradle, check what your consumers actually resolve before assuming either file needs surgery.

We also removed our changes to a second publication path. Its tasks were gated by CI flags, and we could not find a run that used them. The review comment referred to the whole plugin; I had initially read it as a comment about one line. Keeping that extra patch would have meant testing a path we had not shown was active.

A few files, zero module build scripts touched. The SDK modules stopped being part of the fix and went back to being part of the inventory.

The generated POMs and .module files were clean, and the tests passed. Gradle TestKit integration tests also ran a real publication in a scratch build and checked the generated descriptors.

Next I checked what a consuming app would actually resolve.

Proving it from the outside

A clean POM is only part of the check. I needed to know whether an app could resolve the SDK, compile against it, and run its code. So I built a small consumer.

The app used AGP 8.11.1 and one SDK artifact, our core module. I excluded the other internal SDK dependencies to isolate its effect and called one SDK entry point. That limits the result: a real app could still inherit pins from the excluded modules. I built the same app with Kotlin 2.0.21, 2.1.20, 2.2.10, and 2.3.0.

Each local test publication got a fresh throwaway version suffix. Reusing a release version can make it unclear whether a consumer reads the changed descriptor or cached content. Cache behavior depends on the repository type, with separate rules for local Maven repositories; unique versions made this experiment easier to track.

The released SDK gave this baseline:

consumer Kotlin 2.0.21  -> stdlib lifted to 2.2.10, compile FAILED
consumer Kotlin 2.1.20  -> stdlib lifted to 2.2.10, compiles
consumer Kotlin 2.2.10  -> no lift, compiles
consumer Kotlin 2.3.0   -> no lift, compiles

The 2.0 consumer failed while reading stdlib metadata. In part one, detekt’s embedded compiler had handled a two-minor gap, while a three-minor gap produced the phantom findings. Here, two minors were enough to break compilation. Those experiments used different readers and inputs; they did not establish a general compatibility rule. Our goal was to avoid raising the consumer’s stdlib version in the first place.

The first locally published version removed our direct stdlib declarations. The Kotlin 2.0.21 consumer still resolved stdlib 2.2.10 and failed to compile. The publication tests had passed, but the consumer exposed a path they did not cover.

Dependency insight showed the remaining path: our SDK depended on kotlin-parcelize-runtime, which brought in kotlin-android-extensions-runtime and stdlib. Gradle selected the higher stdlib version through that path even after we removed our direct declaration.

To isolate the cause, I forced the consumer’s stdlib down to 2.0.21 while leaving the SDK built with Kotlin 2.2.10. It compiled. There was an important condition: the SDK already used languageVersion and apiVersion 2.0:

This fragment belongs to the SDK modules’ Kotlin compilation tasks under compiler 2.2.10, not a standalone build.gradle.kts. These settings predated the fix. With them, removing the stdlib uplift let the tested SDK code compile and run on 2.0.21. That does not establish compatibility for arbitrary newer Kotlin libraries; JetBrains documents language and API compatibility separately.

The missing half, and the field with the wrong name

The missing step was an exclusion on the SDK’s kotlin-parcelize-runtime dependency. In the tested artifact, kotlin-android-extensions-runtime was transitive, not directly declared. The filter also lists that coordinate so it can add the same exclusion if another publication declares it directly; this case was not established by the core experiment. The simplified graph looks like this:

The exclusion applies below our runtime dependency, not across the consumer’s whole graph. It leaves the app’s own stdlib dependency alone. In a POM, the rule looks like this:

<dependency>
  <groupId>org.jetbrains.kotlin</groupId>
  <artifactId>kotlin-parcelize-runtime</artifactId>
  <version>2.2.10</version>
  <exclusions>
    <exclusion>
      <groupId>org.jetbrains.kotlin</groupId>
      <artifactId>kotlin-stdlib</artifactId>
    </exclusion>
  </exclusions>
</dependency>

And in the Gradle module metadata, the .module file our Gradle consumer resolved, the equivalent is an exclude rule on that dependency. A single dependency entry inside a variant, not the whole file, looks like this, per Gradle’s module metadata specification:

{
  "group": "org.jetbrains.kotlin",
  "module": "kotlin-parcelize-runtime",
  "version": { "requires": "2.2.10" },
  "excludes": [
    {
      "group": "org.jetbrains.kotlin",
      "module": "kotlin-stdlib"
    }
  ]
}

My first attempt used exclusions instead of excludes. The JSON was valid, generation passed, and the consumer failed exactly as before. The resolver ignored the unknown field.

Review identified the field-name mismatch, and a reference descriptor generated by stock Gradle independently confirmed excludes. The consumer build caught the failure first. We then added assertions for the exact POM and .module structures so the same mistake would fail closer to publication.

With the correctly named field in place, the matrix finally flipped:

filter + excludes, no forcing anywhere:
consumer Kotlin 2.0.21  -> keeps own stdlib 2.0.21, compiles
consumer Kotlin 2.1.20  -> keeps own stdlib, compiles
consumer Kotlin 2.2.10  -> compiles
consumer Kotlin 2.3.0   -> compiles

No force was needed in this run: the 2.0.21 consumer kept stdlib 2.0.21.

For readers who want to apply the same check to their own project, it is one command, no scanner required:

./gradlew :app:dependencyInsight \
    --dependency org.jetbrains.kotlin:kotlin-stdlib \
    --configuration debugRuntimeClasspath

Use the configuration for your variant, such as releaseRuntimeClasspath. Check the selected stdlib version and the paths requesting it. In our isolated consumer without its own @Parcelize, the selected version changed from 2.2.10 to 2.0.21, and the SDK’s paths to stdlib disappeared.

The runtime half of the contract

I installed the 2.0.21 app without its own @Parcelize on an emulator and exercised the SDK entry point. It ran with zero observed crashes.

The 2.1 build, the oldest compiler version we tested successfully with the consumer’s own @Parcelize, went further, and this is where the verification itself needed verifying. My original smoke test put a parcelable into a Bundle and read it back, same process, same Bundle. That roundtrips a reference, not bytes: a Bundle keeps the object in memory unless something forces it through a Parcel, so the serialization code never ran. A sharp review pass caught it. The test now marshals for real:

The harness passes the activity’s classloader, then reads the restored objects with getParcelable and checks their fields. Reading forces deserialization. On the 2.1.20 build, both an SDK @Parcelize model and the app's own model passed this roundtrip on the device, with zero observed crashes.

The smoke screen also prints KotlinVersion.CURRENT, which reports the runtime stdlib rather than the compiler version. The 2.0.21 app printed 2.0.21. The 2.1.20 app with its own @Parcelize printed 2.2.10, confirming that stdlib was still being lifted in that case.

The boundary matters, because a fix sold without its boundary is a lie with a release note. A Kotlin 2.0.21 consumer with its own @Parcelize still failed. The consumer and SDK both requested parcelize-runtime; resolution selected 2.2.10, whose metadata the older compiler could not read. Our exclusion applied to the SDK’s path, not the consumer’s separate path. Kotlin 2.1.20 was the oldest version we tested successfully in this setup, including the Parcel roundtrip. This fix does not answer whether a different publication design could support older consumers too.

Here are the results together:

These results cover one isolated SDK artifact: the original entry-point check and the additional model roundtrip described above. Other SDK modules were excluded. Compiling successfully and keeping the consumer’s stdlib version are separate outcomes.

Where this stands

This remains a proposed stopgap. It removes direct stdlib declarations and the tested transitive paths through the SDK’s runtime dependencies. The platform team is looking for a longer-term solution, including the unresolved consumer @Parcelize case.

The checks cover generated descriptors, consumer compilation, and the runtime cases listed above. They do not show that every SDK artifact is compatible or that the policy has been rolled out.

A publisher’s validation checklist

Everything above, compressed into the list I will follow the next time a publish pipeline change lands on my desk:

1. POM and .module from the same generation run. Different tasks generate them, and comparing across runs invents bugs.
2. Unique throwaway versions for every local test iteration, or you will verify yesterday’s cache.
3. Generate a reference descriptor with the stock tooling and diff your format against it before trusting your field names.
4. Assert on the mechanism in integration tests: the node is absent, the exclusion is present, by exact name. Absence of the old failure is not presence of the fix.
5. Check whether compilation inputs changed. UP-TO-DATE tasks are a useful signal, not proof of identical artifacts; compare the artifacts when you need that proof.
6. Build a scratch consumer across the supported toolchain versions. Isolate the artifact under test, and record which dependencies you excluded.
7. The stranger’s runtime, for the versions the claim is about. Install, launch, and print KotlinVersion.CURRENT so "ran on old stdlib" has a witness.
8. Run the fix twice. Idempotency bugs in code that edits XML look exactly like working fixes on the first run.

Item eight came from another review finding. The exclusion code created a new container before checking for an existing one. A dependency that already had exclusions ended up with two containers, while the test inspected only the first and passed. The corrected code reuses the existing container. This shortened regression test checks the result after two runs:

The test uses JUnit 4 (org.junit.Test and org.junit.Assert), the Groovy XML parser, and the helpers above in the same Kotlin file. The deliberately matching artifactId under a different group must not suppress the Kotlin exclusion. Parsing the fixture also catches the QName bug that string-only synthetic nodes missed. Count nodes, do not inspect one. The staircase, as promised.

Takeaways

• Verify the downloaded artifacts and the resolved graph. Fixing one SDK family does not remove requests from another.
• Put publication policy in the publication layer, and check both POM and .module output.
• Test the consumer’s selected dependencies, compilation, and runtime separately. A green result in one does not establish the others.
• Keep compatibility claims tied to the actual setup: language/API versions, included dependencies, exercised code, and known failures.

The nightly is still red as I write this, waiting for the remaining vendor family to publish new versions. Our own publication fix has passed the limited consumer checks described here. Next time, I know where to start.

The scanner, pointed at the nearest mirror.

The Fix Shipped and Nothing Changed: Hunting the Phantom Pins That Outlived It was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Every Android architecture diagram looks clean on day one. Features in boxes, arrows pointing down, a note in the README saying “features must not depend on each other.”

Then a deadline arrives. Someone needs the user’s avatar on the checkout screen, the profile feature already has a UserRepository, and it's one import away. The build is green, the review is busy, and the arrow now points sideways. Six months later nobody can change the profile feature without breaking checkout.

Folders and naming conventions describe an architecture. They don’t enforce it. A rule that only lives in a README is a suggestion.

This article takes six rules a modular Compose app usually lives by, and moves each one out of the README and into the build:

1. Only the app may depend on an implementation. Enforced by a Gradle check.
2. A module’s internals stay private. Enforced by Kotlin’s internal.
3. Only a feature may build its own routes. Enforced by internal routes and launchers.
4. Every dependency has a definition. Enforced by Koin’s compiler plugin.
5. Every failure is handled. Enforced by sealed types.
6. Every feature and route is registered. Enforced by a source check that runs in CI.

Where a rule can’t be enforced, the last section makes the right way the easy way instead.

The shape: every capability is two modules

Each capability becomes a pair of Gradle modules:

• -api says what the capability can do. Interfaces only.
• -impl says how. Screens, view models, repositories, DTOs, wiring.

app/                          the only module that sees implementations
features/
  posts/posts-api             PostsApi, PostsLauncher
  posts/posts-impl            screens, view models, data, Koin module
  counter/counter-api
  counter/counter-impl        depends on posts-api, never posts-impl
core/
  designsystem/               tokens, theme, components
  statemanager/               AppStateViewModel
  router/router-api | impl    Navigation 3
  network/network-api | impl  Ktor
  logger/logger-api | impl    Kermit

Dependencies only point down: app → features → core. Features reach each other only through an -api. When checkout needs the user's avatar, it depends on profile-api and asks through an interface. It never sees UserRepository, and profile is free to rewrite it.

Rule 1: only the app may depend on an implementation

This is the rule everything else rests on. It makes app the composition root: the one place that knows which implementation stands behind each interface. Every other module is written against contracts.

A few lines in a convention plugin check every project dependency as it’s declared:

internal fun Project.applyArchitectureGuard() {
    val self = path
    configurations.configureEach {
        val configurationName = name
        dependencies.withType(ProjectDependency::class.java).configureEach {
            val target = path
            val violation = when {
                target == self -> null // a module's own test classpaths
                target == ":app" -> "nothing may depend on :app"
                target.endsWith("-impl") && self != ":app" ->
                    "only :app may depend on an -impl module; depend on its -api instead"
                else -> null
            }
            if (violation != null) {
                throw GradleException(
                    "Architecture rule broken in $self ($configurationName -> $target): $violation.",
                )
            }
        }
    }
}

Add implementation(project(":features:posts:posts-impl")) to the counter feature, and the build stops during configuration, before it compiles a single file:

Architecture rule broken in :features:counter:counter-impl
(implementation -> :features:posts:posts-impl):
only :app may depend on an -impl module; depend on its -api instead.

The message says what went wrong and what to do instead. The review conversation never has to happen.

Because the check runs on configureEach, it covers every configuration: implementation, api, testImplementation, and any a plugin adds later. And because the rule is about module paths, there's no list to maintain.

Every module gets the guard without asking

A guard only helps if every module has it, and twenty modules with twenty copies of the same build setup will drift apart. So the shared setup lives in build-logic/ as convention plugins, and the Android library and application plugins both call applyArchitectureGuard().

A feature’s build file then says only what is particular to it:

plugins {
    id("modular.feature.impl")
}

dependencies {
    implementation(project(":features:posts:posts-api"))
    implementation(project(":core:network:network-api"))
}

modular.feature.impl brings the Android library setup (and with it the guard), Compose, Koin, serialization, detekt, the design system, the state manager, the router contract, the logger contract and the test libraries. Even the Android namespace is derived from the module path: :features:posts:posts-impl becomes com.example.modularapp.features.posts.impl.

Rule 2: a module’s internals stay private

Kotlin’s internal means "visible inside this Gradle module only." In an -impl module, almost everything is internal: routes, view models, repositories, DTOs.

internal class PostsRepositoryImpl(private val client: NetworkClient) : PostsRepository

The guard stops the wrong dependency from being declared. internal makes sure that even a module allowed to depend on posts-impl, which is only app, finds nothing there except the few classes it needs to wire the feature in.

Rule 3: only a feature may build its own routes

Navigation 3 has a pleasantly simple model: the back stack is a plain observable list of keys, and NavDisplay shows whichever composable belongs to the last key. Going forward adds a key, going back removes one.

The modular question is: who is allowed to create a key? If any feature can build PostDetailsRoute(42), every feature depends on how posts arranges its screens. So routes are private:

// posts-impl: no other module can see these
@Serializable
internal data object PostsRoute : AppRoute

@Serializable
internal data class PostDetailsRoute(val postId: Int) : AppRoute

Other features get a route from the feature’s launcher, published in its -api:

// posts-api
interface PostsApi {
    val launcher: PostsLauncher
}

interface PostsLauncher {
    fun posts(): AppRoute
    fun postDetails(postId: Int): AppRoute
}

The launcher returns a route instead of navigating. The launcher knows where, and the caller decides how: push it, replace the current screen with it, or make it the new root.

// counter-impl, handling an effect from its view model
CollectEffects(viewModel.effects) { effect ->
    when (effect) {
        // Our own screen: use the route directly.
        is CounterEffect.OpenDetails -> navigator.push(CounterDetailsRoute(effect.count))
        // Another feature: only through its launcher.
        CounterEffect.OpenPosts -> navigator.push(postsLauncher.posts())
    }
}

Try to write navigator.push(PostDetailsRoute(42)) in the counter feature and it doesn't compile. The route isn't visible.

Each -impl contributes one ModuleRouter that maps its routes to screens. It's also the one place the feature's view models are built:

class PostsModuleRouter internal constructor(
    private val repository: PostsRepository,
) : ModuleRouter {

    override fun PolymorphicModuleBuilder<NavKey>.registerRoutes() {
        subclass(PostsRoute::class)
        subclass(PostDetailsRoute::class)
    }

    override fun EntryProviderScope<NavKey>.entries() {
        entry<PostsRoute> {
            PostsScreen(viewModel = viewModel { PostsViewModel(repository) })
        }
        entry<PostDetailsRoute> { route ->
            PostDetailsScreen(viewModel = viewModel { PostDetailsViewModel(route.postId, repository) })
        }
    }
}

Two details matter here.

• registerRoutes() is what lets the back stack survive process death. Routes are @Serializable, and because they are private, each feature registers its own subclasses. The app merges them into one serializer.
• Each back-stack entry gets its own ViewModelStore, through Navigation 3's view model decorator. viewModel { … } inside an entry creates a view model that lives exactly as long as that screen stays on the stack.

Navigation is an effect, never a call

Screens follow one State / Event / Effect loop, on the plain AndroidX ViewModel:

user taps ──▶ Event ──▶ ViewModel ──▶ new State ──▶ screen redraws
                            └────────▶ Effect ────▶ screen navigates

A view model never holds a navigator or a Context. It says what should happen, as an effect, and the screen does it. Effects travel through a buffered channel, so one sent while the screen is in the background is delivered when it comes back instead of being lost.

Rule 4: every dependency has a definition

Classic Koin resolves everything at runtime: a missing definition is a crash the first time that code path runs. Koin’s K2 compiler plugin moves that check into the build.

Each -impl has one Koin module. The definitions are functions, so the classes themselves carry no DI annotations at all:

@Module
class PostsKoinModule {
    @Single
    fun postsApi(): PostsApi = PostsApiImpl()

    @Single
    internal fun repository(client: NetworkClient): PostsRepository = PostsRepositoryImpl(client)

    @Single(binds = [ModuleRouter::class])
    internal fun moduleRouter(repository: PostsRepository): PostsModuleRouter = PostsModuleRouter(repository)
}

Read each function as a sentence: to provide a PostsRepository, I need a NetworkClient. The binds on the router lets the app collect every feature's router with koin.getAll<ModuleRouter>(), without naming a single feature.

The app lists every module exactly once:

@Module(
    includes = [
        LoggerKoinModule::class,
        NetworkKoinModule::class,
        CounterKoinModule::class,
        PostsKoinModule::class,
    ],
)
internal class AppKoinModule { /* … */ }

@KoinApplication(modules = [AppKoinModule::class])
internal object ModularKoinApplication

Remove NetworkKoinModule from that list and the app no longer compiles:

e: [Koin][KOIN-D001] Missing dependency: com.example.modularapp.core.network.NetworkClient

Three decisions are worth explaining.

• Why functions instead of annotated classes? @Single class PostsRepositoryImpl with component scanning is shorter, but then every class imports Koin and the wiring is spread across dozens of files. With functions, domain and data code stays plain Kotlin, and each capability's wiring reads in one place.
• Why aren’t view models resolved from Koin? The router builds them with an ordinary constructor call. A post id comes from the route, is passed to the constructor, and the compiler checks it. Resolving the view model from the container would turn that into a runtime parameter lookup.

Rule 5: every failure is handled

Features never import Ktor. They see one interface, and every call returns a value instead of throwing:

interface NetworkClient {
    suspend fun <T> get(
        path: String,
        response: DeserializationStrategy<T>,
        query: Map<String, String> = emptyMap(),
    ): AppResult<T>
    // post(…) likewise
}

sealed interface AppResult<out T> {
    data class Success<out T>(val value: T) : AppResult<T>
    data class Failure(val error: NetworkError) : AppResult<Nothing>
}

NetworkError is a sealed set: no connection, timeout, HTTP status, a body that doesn't decode, unknown. The Ktor implementation catches everything and turns it into one of those, with one deliberate exception: coroutine cancellation is rethrown, so leaving a screen still cancels its request.

Each layer then speaks its own language. The repository translates network errors into the feature’s own failure type, exhaustively:

private fun NetworkError.toFailure(): PostsFailure = when (this) {
    NetworkError.NoConnection -> PostsFailure.NoConnection
    is NetworkError.Http -> if (code == HTTP_NOT_FOUND) PostsFailure.NotFound else PostsFailure.Unavailable
    NetworkError.Timeout, is NetworkError.Unknown -> PostsFailure.Unavailable
    is NetworkError.Serialization -> PostsFailure.Malformed
}

The view model keeps that failure in its state as a value. Only the screen, which has access to resources, turns it into a translated sentence. Because every step is a sealed when with no else, adding a new failure kind won't compile until every layer handles it. There's no "something went wrong" fallback hiding a case nobody thought about.

Rule 6: every feature and route is registered

Some mistakes have the right shape, compile perfectly, and still fail at runtime:

• A feature whose Koin module was never added to the app. Nothing asks for its types, so Koin’s graph looks complete. The feature just has no screens.
• A route missing from registerRoutes(). It navigates fine, then crashes the first time Android saves the back stack.

Neither Gradle nor the compiler can see these, so a Gradle task reads the sources and checks exactly them. ./gradlew doctor runs in CI on every pull request:

doctor found problems:
  ✖ route-not-registered: PostDetailsRoute (posts-impl) is missing from registerRoutes().
  ✖ feature-not-registered: UserProfileKoinModule is not in the app's includes.

It’s a deliberately small tool. It knows the project’s conventions, so it can check what a general-purpose linter never could.

Where the build can’t enforce, make the right way the easy way

Not every rule can be an error. For the rest, the goal is that doing the right thing takes less effort than doing the wrong one.

New features are generated, not copied. The easiest way to avoid wiring mistakes is not to wire by hand. ./gradlew newFeature --name=user-profile generates both modules: facade, launcher, route, route table, Koin module, view model, screen and a test. It also adds the feature to the app. The generated code passes detekt and doctor as it is.

The design system does the accessibility work. It’s built on Compose Foundation rather than Material: a small set of tokens (colours, spacing, radii, typography, motion) provided through composition locals and read through one object:

AppText(text = post.title, style = AppTheme.typography.title)

The tokens use staticCompositionLocalOf. A dynamic composition local tracks every place that reads it, so a change recomposes only those readers. A static one skips that tracking, and a change recomposes the whole subtree instead. For theme tokens that's exactly right: they're read everywhere and change only when the whole theme does.

What it costs

This isn’t free, and pretending otherwise would be a disservice.

• More modules. Two per feature, plus a composition root you have to keep current. Gradle’s configuration cache and build cache keep it fast, but it’s more to navigate.
• Indirection. Opening another feature’s screen goes through an interface and a launcher rather than a direct call. That’s the point, but it’s one more hop when reading code.

My rule of thumb: this pays off from roughly ten features, or two teams working in the same app. Below that, a single module with good discipline is probably fine. Above it, a build that enforces the boundaries is worth far more than it costs.

Everything above is in the open-source modular-compose-template, which opens on a counter screen that browses posts from JSONPlaceholder. The screens are simple on purpose; the wiring around them is the point. If you try any of these rules on a real project, I’d like to hear where they helped and where they got in the way.

Modular Jetpack Compose: Don’t Leave Your Architecture to Code Review was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

TL;DR: Point the device at an HTTPS proxy running on your Mac. The proxy does the DNS lookup, so your Mac’s /etc/hosts becomes the single source of truth for routing. The device only needs to trust one certificate, once. If you want to skip ahead: uvx proxy-lab start android.

GitHub - kibotu/proxy-lab.sh: Android's two HTTPS blockers - device trust and proxy routing - scripted end to end, with pre-flight checks that catch the usual traps first. Pinned, CI-tested, one YAML for both platforms.

The setup you already have

Docker Compose on your Mac. A reverse proxy (Traefik, nginx, Caddy, pick your favorite) listens on 443 and routes by hostname:

mysub.domain.com  ->  api container
auth.domain.com   ->  keycloak container

Your /etc/hosts has the usual line:

127.0.0.1  mysub.domain.com auth.domain.com

Safari opens https://mysub.domain.com and the whole stack works. Nice. So you build the debug app against the same URL, hit run, and get this:

java.net.UnknownHostException: Unable to resolve host "mysub.domain.com"

Or something more exciting: it resolves, because the domain is real and public, and your integration test just wrote a row into production.

Both are fixable with one idea. The rest of this article is why that idea needs a certificate.

The emulator is a different computer

That is the whole thing in one sentence. The Android emulator runs its own kernel with its own network stack and its own resolver, and it has never heard of your /etc/hosts. Neither has the iOS simulator, though for a nicer reason we will get to.

The first instinct is to give the device the same hosts file. On Android that means /system/etc/hosts, a writable system image, and -writable-system on every boot. It works, and you can feel the shape of the problem: the same mapping now lives in two places, and the second one resets itself at the worst time.

The second instinct is to change your base URL to http://10.0.2.2:8080. That address is useful, it is the host machine as seen from the emulator (docs), and for a single service it is the right answer. For a hostname-routed stack it costs more than it saves:

• Your reverse proxy routes on the Host header. Send it 10.0.2.2 and Traefik cannot tell which container you meant.
• TLS stops matching, because the certificate is for mysub.domain.com and you asked for an IP.

Cookies scoped to .domain.com stop being set, and your debug config now differs from production in exactly the places that hide bugs until release day. What you want is for the same URL to mean something different on your machine. That is a DNS question, and one computer here already knows the right answer.

A proxy moves the DNS lookup to the right computer

Here is the part that took me embarrassingly long to internalize. When an HTTP client talks through a proxy, it does not resolve the hostname first. It hands the name over:

CONNECT mysub.domain.com:443 HTTP/1.1

The proxy resolves it. The proxy runs on your Mac. Your Mac’s /etc/hosts says 127.0.0.1. Your Docker reverse proxy is sitting on 127.0.0.1:443 and sees a real Host header and real SNI, so it routes correctly.

Nothing on the device needs to know anything. Same URL, same cookies, same certificate name, same code path as production. Stop the proxy and the device goes straight back to the real internet. That is a lot of value from one setting:

adb shell settings put global http_proxy 10.0.2.2:8080

Note that the setting is device-wide, not app-scoped. Every app on that emulator now goes through the proxy, which matters in a minute.

One certificate to install, and a good reason why

To see and route HTTPS, the proxy terminates TLS. It presents its own certificate, signed by a CA generated on first run at ~/.mitmproxy/mitmproxy-ca-cert.pem. To your app that CA is a stranger, and your app is right to hang up on it.

The side effect is worth the trouble. mitmproxy talks to your Docker stack with verification relaxed (--set ssl_insecure=true), so your self-signed local certificates never need to be trusted by anything. One CA on the device covers every domain in your compose file, today and next month when you add three more. You install one certificate, once, and stop thinking about local TLS.

You do have to actually install it, and that part deserves some context.

Why Android asks for an explicit opt-in

Since Android 7, apps targeting API 24 and above do not trust user-installed CAs by default (Android Developers Blog). This was the right call. A CA that any app or any well-meaning user can add is a CA an attacker can add, and most users cannot reasonably evaluate that prompt.

The old workaround was the system store, which the mitmproxy guide still documents: hash the cert by hand, remount /system, reboot. Android 14 then moved that store into the Conscrypt APEX (AOSP), which is a real improvement, because root certificates now ship as Mainline updates instead of waiting for a full OS release. APEX modules are immutable and /apex is mounted with private propagation, so editing the system store is closed even for root. Tim Perry wrote the definitive walkthrough, and what remains is a Magisk module or nsenter into Zygote's mount namespace. Impressive engineering, and more than most of us need to look at our own JSON.

Google left a proper door for exactly this case, and it has been there since Nougat.

The supported path: debug-overrides

Apps can opt in to the user trust store per build type with a network security config. Put this in your debug source set as res/xml/network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="user" />
        </trust-anchors>
    </debug-overrides>
</network-security-config>

Reference it from the <application> tag in your manifest. <debug-overrides> only applies when the build is debuggable, so it cannot weaken a release build even if it ships (docs). Keep it in the debug source set anyway, because reviewers should not have to know that rule by heart.

Supported, survives OS upgrades, no Magisk, no writable system image. Your app now trusts the user store.

The certificate still has to get in there, and that store is not the one in Settings. It lives at /data/misc/user/0/cacerts-added/ and it has opinions:

1. The filename must be the certificate’s subject hash plus .0. It is subject_hash_old, the OpenSSL 1.0 algorithm, not subject_hash.
2. Mode 644, then restorecon, so the SELinux label is right.
3. You need adb root, which means a Google APIs system image. Play Store images decline with adbd cannot run as root in production builds, which is accurate and says nothing about images.
4. Reboot, then adb root again, because adbd returns to the shell user after a reboot and the shell user cannot read that directory.

Each of those four can go wrong without crashing or logging anything. You get ERR_CERT_AUTHORITY_INVALID and no hint about which one it was. Once they are all right, the certificate survives reboots and you never touch it again for that AVD.

iOS gets to skip most of this

The simulator has no network stack of its own. It borrows the Mac’s, which is why 127.0.0.1 already works and why DNS is not a topic here.

That also means it has no proxy setting of its own. Either set the proxy for the whole Mac in System Settings > Network > (interface) > Details > Proxies, or set connectionProxyDictionary on your URLSessionConfiguration for just your app. Then, once per simulator: open mitm.it in Safari (it is served by the proxy, so start the proxy first), install the profile under VPN & Device Management, and flip the switch under General > About > Certificate Trust Settings.

Three steps, no root, no reboot. Apple gets real credit for that one.

Count the steps, then stop doing them by hand

For one Android emulator, from cold:

Install mitmproxy at a known version. Generate the host CA. Boot an AVD, and make sure it is a Google APIs image. adb root. Hash the cert with the right algorithm. Create the directory with the right mode. Push the file under the right name. chmod and restorecon. Reboot. Wait for sys.boot_completed. adb root again. Check nothing else is on port 8080. Set the global proxy. Start the proxy. Clear the global proxy on exit, or the device keeps pointing at a socket that is gone.

Fourteen steps, a handful of quiet failure modes, all of it mechanical. Mechanical is good news, because that is what scripts are for.

It is also worth pricing out if you lead a team. Those steps are the difference between a new hire seeing their first intercepted request on day one or on day three, and between everyone’s emulator behaving the same or each one being quietly personal. A pinned mitmproxy version means a bug you reproduce is a bug they reproduce.

So I put it in a script

proxy-lab.sh runs those steps and checks the preconditions before it touches anything:

uvx proxy-lab.sh proxy-lab start android

First run on a cold machine:

✓ tools       adb, uv, openssl, lsof
  ✓ host CA     ~/.mitmproxy/mitmproxy-ca-cert.pem
  … emulator    booting Pixel_9_API_35
  ✓ emulator    Pixel_9_API_35 booted in 38s
  … device CA   installing c8750f0d.0, one reboot, once per AVD
  ✓ device CA   c8750f0d.0 trusted
  ✓ port 8080   free
  ✓ proxy       10.0.2.2:8080 set
  ✓ mitmdump    0.0.0.0:8080, Ctrl-C to stop

[local_router] https://mysub.domain.com/v1/session
[local_router] https://auth.domain.com/realms/dev/protocol/openid-connect/token

The second run on the same AVD skips to the last two lines. uv pins mitmproxy to one version, so the whole team sees identical behavior and nobody installs Python.

Add the hostnames from your compose file to a YAML list and they get tagged in the output, which matters once your app is making two hundred requests a minute:

domains:
  - ".domain.com"

uvx proxy-lab.sh proxy-lab start android my-domains.yml

Pin the tag, put that line in your Makefile, and commit the domains file next to it. Onboarding becomes one command that behaves the same on every machine. iOS is the same command with ios, and a much thinner wrapper, for all the reasons above.

What it touches

Reasonable question before running a git URL that roots your emulator. The Android script is 279 lines of bash and the iOS one is 38, so you can read both in a sitting, and you should. What they do:

• Nothing is installed globally. uv runs mitmproxy from its own cache at a pinned version. Clear the cache and it is gone.
• The CA goes into the emulator’s user store. Only builds that opted in through debug-overrides care that it exists.
• The port check stops stale mitmdump processes from earlier runs and refuses to touch anything else. Your dev server on 8080 gets an error message, not a signal.
• Ctrl-C clears the device proxy setting. If you kill -9 instead, the next run cleans up after you.
• The emulator keeps running after the proxy stops. The script boots it, it does not own it.

The failure messages got more attention than the automation did. Missing tool, Play Store image, busy port, wrong AVD name: each one prints the fix instead of a stack trace.

The edges worth knowing

Being upfront about these, because you will meet them anyway:

• Not every HTTP client uses the system proxy. OkHttp and URLSession do, so stock Android and iOS work out of the box. Dart's HttpClient needs findProxy, and Cronet needs its own configuration. If traffic is missing, check the client before you suspect the certificate.
• The proxy setting is device-wide. Other apps on the emulator route through it too, and the ones that never opted into the user store will fail TLS while it runs. Same reason Android may show a “No internet connection” banner: the connectivity probe does not use user CAs. Your app is unaffected.
• Certificate pinning wins, as designed. A pinning app will reject the proxy CA. Turn pinning off in debug builds.
• Cleartext still needs opting in. Plain HTTP locally means usesCleartextTraffic on Android and an ATS exception on iOS. Or serve TLS locally, which you already are if you followed along.
• Emulator and simulator only. Physical devices need root for the user store, and that is a different article by someone who knows more about it than I do.

How do you handle this?

This is not the only sane approach and I would like to hear the others. Some teams run a DNS server inside the compose stack and point the emulator at it. Some register a real domain whose A record is 127.0.0.1 and take certificates from Let's Encrypt, which sidesteps the CA question for about twelve dollars a year. Some use HTTP Toolkit, which automates the hard Android 14 path properly and comes with a UI.

If you have a cleaner answer, or if the script trips on your setup, the issues are open and real failure reports are the most useful thing anyone can send me. Paste the exact error line. The scripts are built to fail loudly, so that line is usually the whole diagnosis.

And if this saved you an afternoon, a coffee is a nice way to say so. Entirely optional. The bug reports are worth more.

Proxy your Android emulator and iOS simulator to your local Docker stack was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Why some of the most elegant APIs in Kotlin — first<T>(), Gson().fromJson<T>(), Jetpack’s viewModels<T>() — could never have existed without two keywords most developers use daily but rarely stop to understand.

inline fun  makeInstance(): T =
    T::class.java.getDeclaredConstructor().newInstance()

Generics on the JVM have a strict rule: you cannot use a type parameter T at runtime. Calling T::class, instantiating new T(), or checking if (x is T) is normally forbidden. The compiler will complain that the type information is missing.

Yet, this function compiles and works flawlessly.

The secret lies in two keywords: inline and reified. Understanding how they interact changes how you read idiomatic Kotlin, from JSON parsers to network clients.

The Problem: The JVM’s Amnesia

When you write generic code, you use T as a placeholder for a future type:

class Box(val value: T)

val intBox = Box(5)          // T is Int
val stringBox = Box("hello") // T is String

At compile time, Kotlin knows exactly what T is. It uses this knowledge to catch mistakes, immediately stopping you if you try to put a String into intBox.

But when compiled to run on the JVM, this knowledge vanishes. This design decision is called type erasure.

Introduced for backward compatibility in 2004, Java’s generics are largely a compile-time illusion. At runtime, the JVM simply sees “a Box holding an Object." The concrete type is erased.

Because of this, you cannot use a generic type parameter as a real class at runtime. In standard Java, the workaround is tedious: you must manually pass a Class token everywhere just to keep the type around.

Kotlin found a way to bypass this entirely.

The First Half of the Trick: inline

To understand the solution, we first need to look at inline—a keyword that originally has nothing to do with generics.

Normally, a function call is a detour. The program jumps to the function’s location in memory, executes it, and jumps back. Every caller shares one compiled copy of the function.

Marking a function inline changes this. Instead of jumping to the function, the compiler physically pastes the function's code directly into the caller.

inline fun measureAndLog(label: String, block: () -> Unit) {
    val start = System.currentTimeMillis()
    block()
    println("\(label took\){System.currentTimeMillis() - start}ms")
}

When you call measureAndLog, the function boundary disappears. The compiler takes the logic and drops it exactly where you made the call.

While primarily used to speed up functions that take lambdas, this copy-paste mechanic creates a fascinating loophole for generics.

The Second Half: reified

Because an inlined function’s body is physically copied into the caller, the compiler already knows the concrete types being used at that exact location.

There is no longer a function boundary for the generic type to be erased across. The code is sitting right there alongside the real types.

Kotlin lets you exploit this with the reified keyword

inline fun  makeInstance(): T =
    T::class.java.getDeclaredConstructor().newInstance()

The reified keyword tells the compiler: do not erase this type. Keep it real.

When you call makeInstance(), the compiler pastes the code and replaces every mention of T with User. It acts exactly as if you had hardcoded User::class.java yourself.

This brings us to the golden rule of Kotlin generics: reified only works on inline functions. Standard functions are compiled once as a shared unit, meaning they still suffer from type erasure.

The Hidden Cost in Tooling

This brilliant workaround has one minor catch regarding code metrics.

Because inlined functions are duplicated rather than invoked like standard methods, code coverage tools (like JaCoCo) often fail to track them correctly.

Your tests might cover the logic flawlessly, but the coverage report will show 0% for the original generic function. It is a harmless compiler artifact, but knowing about it will save you hours of debugging your test suite.

Type erasure is a permanent JVM limitation. But by physically relocating code with inline and preserving types with reified, Kotlin turns a rigid platform constraint into an invisible implementation detail.

Why Kotlin’s inline and reified Keywords Exist (And How They Solve Java’s Oldest Flaw) was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Ask an AI assistant to help you prepare for a developer conference. A text response can give you a checklist. An interactive response can let you tick an item, inspect the venue, and ask the assistant to update your plan using what you have already completed.

That second interaction is what we built in PocketCommunity, the latest app in the Android Engineers Android + AI Cookbook.

The app reads published developer-event listings from DevEarth. Gemini composes an interface from a restricted set of components. A companion server validates that composition, and the AndroidX A2UI renderer displays it using native Jetpack Compose components.

The interesting engineering problem starts after the first card appears: how does a tap become agent context, and how do we keep the next generated screen consistent with the user’s current state?

What actually generates the screen?

A2UI is a protocol, not an inference provider. Its renderer does not require a Gemini key. It can render a developer-authored message just as it can render one produced by an agent.

PocketCommunity uses Gemini as the producer, so our server needs a Gemini credential. The Android app needs the server URL. These are different responsibilities.

In this implementation, Gemini returns:

{
  "text": "Here is a preparation checklist for your event.",
  "components": [
    { "id": "root", "component": "Column", "children": ["heading"] },
    { "id": "heading", "component": "Text", "text": "Before you go" }
  ]
}

This is a minimal illustrative composition, not a complete event response. The server validates the components and wraps them in A2UI messages. Gemini does not generate Kotlin, and the app does not compile code received from the model.

The official Compose A2UI guide describes the separation between the rendering engine and the catalogs that map protocol components to native implementations. Our app adds the Gemini producer, event-data boundary, and application-specific validation around that renderer.

Gemini chooses the composition; the server validates it; Android renders registered native components.

In the shipped preview, no configured endpoint means setup — not a simulated AI response. Deterministic messages remain useful in instrumentation tests, where we explicitly inject a fake repository. They are not a runtime fallback.

Source: PocketCommunity at the article’s pinned revision.

A surface has structure and state

Think about a single preparation checklist. It needs a component tree, but it also needs values that can change when the user interacts.

A2UI separates these concerns. In PocketCommunity, the server constructs three messages for each new response surface:

1. createSurface identifies the surface and its catalog.
2. updateDataModel supplies initial values.
3. updateComponents supplies the component graph.

Here is a compact example matching the pinned implementation’s wire format:

[
  {
    "version": "v0.9",
    "createSurface": {
      "surfaceId": "preparation-1",
      "catalogId": "https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json",
      "sendDataModel": true
    }
  },
  {
    "version": "v0.9",
    "updateDataModel": {
      "surfaceId": "preparation-1",
      "path": "/",
      "value": { "ready0": false }
    }
  },
  {
    "version": "v0.9",
    "updateComponents": {
      "surfaceId": "preparation-1",
      "components": [
        { "id": "root", "component": "Column", "children": ["pack"] },
        {
          "id": "pack",
          "component": "CheckBox",
          "label": "Pack a charger",
          "value": { "path": "/ready0" }
        }
      ]
    }
  }
]

pack identifies a component. /ready0 identifies a value in the surface’s data model. They are not interchangeable.

When the user checks the item, the bound value changes. The UI can reflect that change without another model call.

A version detail matters here: the current Android guide describes specification 0.9.1 support, while this pinned alpha implementation uses v0.9 and the v0_9 catalog URL in its messages. Keep the tested dependency and protocol values together rather than editing version strings to match a documentation heading.

The sample currently receives a complete HTTP response containing the message batch. Processing multiple messages does not mean we have implemented token streaming or an SSE transport.

One response batch becomes a surface through the parser, processor, and Material catalog.

The catalog is your UI contract

The server allows eight component types:

const allowed = new Set([
  'Text', 'Column', 'Row', 'Card',
  'Button', 'CheckBox', 'Divider', 'Image'
]);

This is our sample’s subset, not the entire A2UI component vocabulary.

On Android, communityCatalog() configures the Material basic catalog. We supply a custom image implementation that recognizes only asset://community and renders bundled artwork. Generated output cannot turn that component into an arbitrary remote image request.

The catalog’s URL opener also rejects direct navigation. Website and directions actions go through application code, which resolves the official HTTPS link from a known event record.

This keeps the agent’s freedom specific: it can choose headings, group supported components, and offer permitted actions. The app still owns its component implementations and the effects those actions can trigger.

The conversation header, composer, setup dialog, and inspector are ordinary Compose UI. The response surfaces are rendered from A2UI messages. An agent-generated experience does not require handing the whole application shell to the model.

Keep inference outside the Composable

We use a small repository boundary:

interface CommunityRepository {
    suspend fun discover(): List<CommunityEvent>
    suspend fun ask(endpoint: String, request: AgentRequest): AgentReply
}
data class AgentReply(
    val text: String,
    val messages: List<String>,
)

CommunityViewModel owns request coordination, conversation state, the message processor, and outgoing action handling. Compose observes state and sends user intent.

This is useful for a concrete reason: tests can replace the network repository while exercising the real native renderer and action flow. We do not need a live Gemini request to prove that a rendered button dispatches the expected event.

Request ownership also matters. A response from an old conversation must not appear after the user starts a new one. The implementation cancels its job and advances a generation counter on reset; after a repository call returns, it checks coroutine activity and whether the request still belongs to the current generation.

There is an important limit: the repository uses synchronous OkHttp calls on Dispatchers.IO. Cancelling the coroutine does not automatically establish immediate transport cancellation or stop provider computation. UI ownership and network cancellation are separate engineering concerns.

A checkbox-aware agent needs more than chat history

Suppose the user checks “Pack a charger” and then taps Update my plan.

If the next request contains only “Update my plan,” the agent has no reliable description of what changed. Even sending the visible conversation text is insufficient: checkbox values are not necessarily written into that text.

PocketCommunity forwards:

• The current request and selected event ID.
• Recent conversation text.
• The actual action name, originating surface/component IDs, and context.
• Previous component trees.
• Snapshots of bound surface values.

A button’s generated action looks like this:

{
  "event": {
    "name": "refine",
    "context": { "eventId": "published-event-id" }
  }
}

The ID above is a placeholder; real actions must reference a current published event.

The ViewModel resolves that ID before proceeding. venue, prepare, and refine become agent requests. website and directions use known listing URLs. save remembers the event for the session and explicitly does not register the user.

The request context is bounded: up to 12 text turns, three previous component trees, and six surface snapshots. These are sample limits, not a complete token-budgeting or conversation-memory system.

A checkbox changes local state; a later agent request carries the state and the originating action.

The bug that exposed the state boundary

During a physical-device check, Gemini correctly responded that one of four items was complete. But the newly rendered checklist showed every checkbox unchecked.

The agent had received the state. The UI initialization discarded it.

Our server was initializing every checkbox in the new surface to false. The fix was to carry the relevant values into the new surface’s initial data model:

const prior = new Map(
  previousChecklist.map(item => [item.label, item.checked])
);
const value = {};
for (const component of reply.components) {
  if (component.component === 'CheckBox') {
    value[component.value.path.slice(1)] =
      prior.get(component.label) === true;
  }
}

On refine, the server finds the originating surface’s earlier components and values, then matches exact labels. An existing item can retain its checked value even if its binding path changes. A new or renamed item starts unchecked.

This is an application-level migration policy, not automatic A2UI persistence. Exact-label matching is also a deliberate preview limitation. Stable domain item IDs would be stronger if the agent edits wording, two items share text, or older context falls outside the retained window.

The corrected flow was verified on the phone: the generated progress text and the new checkbox state agreed.

Actual PocketCommunity output after refinement: one item remains checked. Completion is self-reported, not externally verified registration.

Valid JSON is only the first check

A syntactically valid response can still reference missing components, create a cycle, invent an action target, or describe a misleading event.

The sample validator checks component names and properties, ID uniqueness, graph references, cycles, reachability, graph depth, action names, published event IDs, checkbox paths, and output limits. Android then checks the expected message envelope and surface identity before passing messages to the official processor.

These checks answer different questions from factual evaluation. A valid Text component can still contain an incorrect venue or an invented agenda. Event facts must be compared with the source feed. A checked registration item means the user marked it complete—not that our application verified a ticket purchase.

One instructive gap remains in the published baseline: two independent checklist components can bind to the same /ready0 path. Their component IDs can be unique while their values remain shared.

That is the practical exercise in our PocketCommunity codelab. You write a failing test, add a per-surface duplicate-path policy, and rerun the suite. The policy is specific to independent checklist tasks; shared bindings can be intentional in other interfaces.

What we verified — and what remains

The published app checkpoint passed debug and release builds, two JVM tests, three physical-device instrumentation tests, and ten Node tests. The instrumentation tests use a fake repository with the real renderer. Separately, live Gemini generation was exercised on a OnePlus DN2101 running Android 13: event discovery, venue details, preparation, and checkbox-aware refinement.

That distinction is worth preserving in your own reports. A passing UI test is not evidence of successful inference. A successful inference is not a comprehensive usability evaluation.

This remains a learning preview. Conversations are not restored after process death; saves are session-only; embedded maps and streaming transport are not implemented. The companion service binds to localhost and does not provide production authentication, per-user quotas, or rate limiting. The A2UI dependencies are alpha and pinned together.

Build it, then improve it

The source includes the Android app, companion server, tests, setup instructions, and diagrams:

git clone https://github.com/AndroidEngineers/android-ai-cookbook.git
cd android-ai-cookbook
git switch --detach 33ff08b56b3e5f00240c99cf2848f0e35bdde998
git switch -c learning/pocketcommunity
cd a2ui

Open a2ui/ in Android Studio. The Gemini key belongs in server/.env; the phone’s Setup field takes the agent endpoint. The README covers Node setup, the pinned Java toolchains, and ADB reverse for a connected phone.

Choose the learning route that fits how you work:

• Follow the codelab: configure the app, trace real messages, implement the validator improvement, and verify it with tests.
• Study the roadmap: 12 units covering catalogs, protocol state, request ownership, action feedback, validation, and an independent capstone.
• Explore the Android + AI Cookbook: PocketCommunity joins PocketCards, PocketCook, PocketChat, and PocketStories in our collection of focused Android learning apps. Each sample documents its own readiness and limitations.

If you build on PocketCommunity, show us the interaction after the first response: what did the user change, what did the agent receive, and how did the next native screen preserve that meaning?

That is where an impressive generated card becomes an Android engineering project you can explain and test.

From a prompt to native Compose UI: building PocketCommunity with A2UI was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.

When we model a Compose screen with a single UiState, a natural question appears:

Where should UI events live?

A snackbar, navigation, or dialog is not really persistent screen state. It is something the UI needs to react to once.

Still, putting events directly into UiStatecan be useful. It keeps the screen driven by one observable state source and avoids introducing another mechanism such as SharedFlowor Channel.

One-Time Events in Jetpack Compose: Why I Switched from SharedFlow to Channel

The interesting part is not whether we can put events into UiState.

Android Architecture Is Moving from Event-Driven UI to State-Driven UI

It is deciding how much event machinery we actually need.

There are three useful levels.

1. Start with a Single Event

For many screens, one nullable event is enough.

sealed interface UiEvent {
    data class ShowSnackbar(val message: String) : UiEvent
    data class NavigateToDetail(val id: String) : UiEvent
    data class ShowDialog(val type: DialogType) : UiEvent
}

data class UiState(
    val isLoading: Boolean = false,
    val items: List<Item> = emptyList(),
    val event: UiEvent? = null,
)

The ViewModel produces the event:

fun onSaveClicked() {
    _uiState.update {
        it.copy(event = UiEvent.ShowSnackbar("Saved"))
    }
}

fun onEventConsumed() {
    _uiState.update {
        it.copy(event = null)
    }
}

And the UI consumes it:

LaunchedEffect(uiState.event) {
    when (val event = uiState.event) {
        is UiEvent.ShowSnackbar -> {
            snackbarHostState.showSnackbar(event.message)
            viewModel.onEventConsumed()
        }

        is UiEvent.NavigateToDetail -> {
            navController.navigate("detail/${event.id}")
            viewModel.onEventConsumed()
        }

        is UiEvent.ShowDialog -> {
            // ...
            viewModel.onEventConsumed()
        }

        null -> Unit
    }
}

This has a nice property: everything is still StateFlow.

There is no second stream to understand and no separate event lifecycle to manage.

For a screen where events normally happen one at a time, this is often all we need.

The limitation becomes obvious when two events are produced before the UI consumes the first one.

Save
 ├─ ShowSnackbar
 └─ NavigateToDetail

With a single event field, the second update can replace the first.

The latest event wins.

There is another subtle issue. LaunchedEffect uses its keys to determine whether the effect should restart. If two consecutive events are equal, changing the state may not produce a new effect execution.

So the single-event pattern is intentionally simple.

2. Add a Queue When Events Can Accumulate

If a screen genuinely needs to handle multiple events in sequence, we can make the event field a queue.

data class UiState(
    val isLoading: Boolean = false,
    val items: List<Item> = emptyList(),
    val eventQueue: List<UiEvent> = emptyList(),
)

The ViewModel appends events:

private fun sendEvent(event: UiEvent) {
    _uiState.update {
        it.copy(eventQueue = it.eventQueue + event)
    }
}

fun onSaveClicked() {
    sendEvent(UiEvent.ShowSnackbar("Saved"))
    sendEvent(UiEvent.NavigateToDetail(savedId))
}

The UI handles the first event:

LaunchedEffect(uiState.eventQueue) {
    val event = uiState.eventQueue.firstOrNull()
        ?: return@LaunchedEffect

    when (event) {
        is UiEvent.ShowSnackbar ->
            snackbarHostState.showSnackbar(event.message)

        is UiEvent.NavigateToDetail ->
            navController.navigate("detail/${event.id}")

        is UiEvent.ShowDialog -> {
            // ...
        }
    }

    viewModel.onEventConsumed()
}

Consumption removes the first item:

fun onEventConsumed() {
    _uiState.update {
        it.copy(eventQueue = it.eventQueue.drop(1))
    }
}

Now multiple events can survive at the same time.

eventQueue
┌───────────────┐
│ ShowSnackbar  │ ← consume
├───────────────┤
│ Navigate      │ ← next
└───────────────┘

This is a meaningful step up from the single-event approach.

But it also introduces a new failure mode:

the queue depends on consumption happening correctly.

If the UI fails to call onEventConsumed(), the first event remains at the head of the queue and later events cannot progress.

The queue is therefore useful when multiple events are a real requirement, not simply because queues look more robust.

3. Add IDs When Consumption Needs to Be Explicit

There is one more step.

Instead of treating an event as "the first item in the list," we can give every queued event its own identity.

data class QueuedEvent(
    val id: Long,
    val event: UiEvent,
)

data class UiState(
    val isLoading: Boolean = false,
    val items: List<Item> = emptyList(),
    val eventQueue: List<QueuedEvent> = emptyList(),
)

The ViewModel creates a unique queue entry:

private fun sendEvent(event: UiEvent) {
    _uiState.update {
        it.copy(
            eventQueue =
                it.eventQueue + QueuedEvent(
                    id = System.nanoTime(),
                    event = event
                )
        )
    }
}

Consumption can now identify exactly which event was handled:

fun onEventConsumed(id: Long) {
    _uiState.update { state ->
        state.copy(
            eventQueue =
                state.eventQueue.filterNot { it.id == id }
        )
    }
}

The UI uses the ID as the effect key:

LaunchedEffect(uiState.eventQueue.firstOrNull()?.id) {
    val queued =
        uiState.eventQueue.firstOrNull()
            ?: return@LaunchedEffect

    when (val event = queued.event) {
        is UiEvent.ShowSnackbar ->
            snackbarHostState.showSnackbar(event.message)

        is UiEvent.NavigateToDetail ->
            navController.navigate("detail/${event.id}")

        is UiEvent.ShowDialog -> {
            // ...
        }
    }

    viewModel.onEventConsumed(queued.id)
}

The important difference is not the ID itself.

It is the identity of the queued item.

The UI is no longer saying:

“Remove the first event.”

It is saying:

“I consumed this particular event.”

That makes the contract more explicit and avoids coupling consumption to the event’s position or value.

The Real Design Question

The important question is not:

”Which event architecture is the best?”

It is:

”What guarantees does this screen actually need?”

• One UI event at a time
  → Single nullable event
• Multiple events must survive
  → Queue
• Events need explicit identity
  → Queue + ID
• No event accumulation is possible
  → Single event is usually enough
• Lost events are unacceptable
  → Consider stronger event semantics

This also changes how we think about UiState.

A UiState does not have to contain only persistent data such as:

• isLoading
• items
• selectedItems

It can also represent what the UI should do next, as long as the lifecycle and consumption semantics are clear.

The mistake is not putting an event into UiState.

The mistake is adding more machinery than the screen actually needs.

Start with the smallest state model that works.

Then make the model more explicit when the requirements force you to.

That keeps UiState simple without pretending that every UI event has the same delivery requirements.

However, in reality, I feel like the MVI style using Channels or SharedFlow for UiState is actually what’s popular.

What do you all think?

• 10 Flow Operators for Building a Declarative UiState
• ViewModel Doesn’t Hold UiState. It Derives It.

Enjoyed this article? Here’s how you can support my work:

• 👏 Clap (up to 50 times!) if you found this insightful.
• 👤 Follow me and turn on notifications 🔔 so you never miss the next deep dive.
• 📧 Subscribe to get my latest stories delivered directly to your inbox.

You can find all my articles on Android architecture, Jetpack Compose, and Kotlin in this curated reading list.

UI Events in UiState: Start Simple, Add a Queue Only When You Need One was originally published in ProAndroidDev on Medium, where people are continuing the conversation by highlighting and responding to this story.