← The playbook

App modernization

Breaking an Android monolith: the order that works

I led the modernization of a large production Android app, end to end. The codebase went from one tightly coupled module to feature slices with clear owners. Cold startup dropped 31%. Product teams started shipping in parallel.

The structure itself is easy to describe. Each feature is three Gradle modules: data, domain and ui. Shared infrastructure like analytics, networking and remote config lives in :core-* modules. Two principles hold the whole thing together: separation of concerns and dependency inversion. The hard part is the order you do it in.

Two principles, applied without exceptions

Separation of concerns means each module has one job and one reason to change. Drawing state on screen, deciding a business rule and fetching remote data are three different jobs, so they live in three different modules.

Dependency inversion means the important code doesn't depend on the details. The domain says what it needs as an interface. The data layer or a core module supplies it.

A typical monolith breaks both in a single class. An Activity or ViewModel calls Retrofit, parses the DTO, formats the display string and logs the analytics event. Taking a monolith apart is mostly the work of untangling that, safely and a little at a time.

The shape to aim for

The code is cut two ways: by feature, so each team owns a slice, and inside each feature into three modules, so the compiler holds the layers apart.

Target module graphmodule names are examples
:appWires features together and binds implementations. No business logic.
depends on ↓
:feature-search-*
ui
screens, ViewModels
domain
use cases, interfaces
data
repositories, APIs
ui → domain ← data
:feature-profile-*
ui
screens, ViewModels
domain
use cases, interfaces
data
repositories, APIs
ui → domain ← data
× never another feature's ui or data, only its domain
depends on ↓
:core-analytics
:core-network
:core-config
:core-ui
Arrows show compile-time dependencies. Inside a feature, both ui and data point at domain, and domain depends on neither.
  1. :app assembles the features and binds implementations through dependency injection. It holds no business logic.
  2. A feature owns one user-facing area. When it needs another feature, it depends on that feature's domain, the contracts it chooses to share, and never on its ui or data.
  3. A feature is ui, domain and data. The first and last depend on domain. domain depends on neither.
  4. Core modules expose narrow interfaces and know nothing about features.

Why three modules and not three packages

A package boundary holds as long as everyone remembers it. A module boundary is held by the compiler.

  • A screen in ui can't construct a repository implementation, because data isn't on its classpath.
  • domain uses the plain Kotlin JVM plugin. A stray android.content.Context import fails to compile, and the unit tests run in milliseconds.
  • Editing a mapper in data recompiles data and :app. ui stays cached.
Kbuild.gradle.ktsfeature/search/domain
plugins { id("myapp.kotlin.library") }   // pure Kotlin JVM, no Android SDKdependencies {    implementation(libs.javax.inject)     // only @Inject, nothing else}// feature/search/data/build.gradle.ktsplugins {    id("myapp.android.library")    id("myapp.android.hilt")}dependencies {    implementation(project(":feature-search-domain"))    implementation(project(":core-network"))    implementation(project(":core-config"))}// feature/search/ui/build.gradle.ktsplugins { id("myapp.android.feature") }dependencies {    implementation(project(":feature-search-domain"))    implementation(project(":core-analytics"))    implementation(project(":core-ui"))}

One naming rule matters more than it looks. Gradle identifies a module by its group and its name, and the name is only the last part of the path. Nest the paths as :feature:search:domain and every feature ends up with modules all named domain, data and ui. Once one feature depends on another feature's domain, Gradle can mistake one domain for the other, and tools such as coverage reports start describing the wrong module. So the names stay flat and unique, like :feature-search-domain, while the folders keep their tidy nesting:

Ksettings.gradle.ktsproject root
// Flat, unique module names. The folders stay nested on disk.listOf("domain", "data", "ui").forEach { layer ->    include(":feature-search-$layer")    project(":feature-search-$layer").projectDir = file("feature/search/$layer")}

Inside the three modules

The domain module holds plain Kotlin models, use cases, and the repository interfaces. The business logic owns those interfaces, because it's the one with the need.

KSearchCatalog.kt:feature-search-domain
data class SearchResult(val id: String, val title: String)interface SearchRepository {    suspend fun search(query: String): List<SearchResult>}class SearchCatalog @Inject constructor(    private val repository: SearchRepository,) {    suspend operator fun invoke(query: String): List<SearchResult> {        val cleaned = query.trim()        return if (cleaned.length < 2) emptyList() else repository.search(cleaned)    }}

The data module implements them. It deals with DTOs and caching, and its classes are internal.

KRemoteSearchRepository.kt:feature-search-data
internal class RemoteSearchRepository @Inject constructor(    private val api: ApiClient,    private val config: AppConfig,) : SearchRepository {    override suspend fun search(query: String): List<SearchResult> =        api.get<List<SearchResultDto>>(            path = "search",            query = mapOf("q" to query, "limit" to config.searchPageSize.toString()),        ).map { it.toDomain() }}

The ui module holds ViewModels and Compose screens. A ViewModel calls use cases and exposes one immutable state.

KSearchViewModel.kt:feature-search-ui
@HiltViewModelclass SearchViewModel @Inject constructor(    private val searchCatalog: SearchCatalog,    private val analytics: Analytics,) : ViewModel() {    private val _state = MutableStateFlow(SearchUiState())    val state: StateFlow<SearchUiState> = _state.asStateFlow()    private var searchJob: Job? = null    fun onQueryChanged(query: String) {        _state.update { it.copy(query = query) }        searchJob?.cancel() // a newer query makes the old search irrelevant        searchJob = viewModelScope.launch {            val results = searchCatalog(query)            _state.update { it.copy(results = results) }            analytics.track("search_performed")        }    }}

Core modules for what everyone needs

Core moduleInternal responsibilityPublic contract
:core-analyticsVendor SDK initialization, batching, user consentAnalytics interface with track()
:core-networkOkHttp/Ktor client, auth interceptors, retriesApiClient interface
:core-configRemote config sync, feature flag evaluationAppConfig interface
:core-uiDesign system theme, typography, reusable componentsStateless Composables and tokens

The order that works

1. Convention plugins first

Put compiler flags, dependencies and test setup into build-logic plugins and a version catalog. Three modules per feature is only bearable if adding them takes ten lines of build script.

2. Wrap the core, then extract it

Before any feature moves, put networking, analytics and config behind interfaces while they're still inside the monolith. Move the callers onto those interfaces. Then lift each one out into a :core-* module.

3. Sort into packages where the code sits

Take one feature and sort its classes into ui, domain and data packages inside the monolith. Pull the logic out of Fragments into use cases. Stop DTOs reaching the screen. Main stays green the whole time, because nothing has changed modules yet.

4. Extract one whole slice

Move domain first, since it depends on nothing. Then data. Then ui. Take that one feature all the way, with its resources, navigation and tests. It becomes the template every other team copies.

5. Bind in :app

KSearchDataModule.kt:feature-search-data
@Module@InstallIn(SingletonComponent::class)internal abstract class SearchDataModule {    @Binds    abstract fun bindSearchRepository(        impl: RemoteSearchRepository,    ): SearchRepository}

6. Decouple navigation between features

When feature A has to open feature B, B publishes a small navigation contract in its domain, A depends on that, and :app supplies the route. A never sees B's screens.

7. Enforce it in CI

Add dependency checks so a reach into another feature's ui or data, or an Android import in a domain module, fails the build right away.

Three ways I've seen this go wrong

  • Layers across the whole app. One global ui, one domain and one data gives you three coupled monoliths and no team owns anything.
  • A catch-all :common. Unrelated utilities in one shared module is the monolith again under a new name.
  • Stopping feature work. A freeze for a full rewrite rarely survives the pressure to ship. Migrate slice by slice, on main.