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.
:appassembles the features and binds implementations through dependency injection. It holds no business logic.- 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 itsuiordata. - A feature is
ui,domainanddata. The first and last depend ondomain.domaindepends on neither. - 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
uican't construct a repository implementation, becausedataisn't on its classpath. domainuses the plain Kotlin JVM plugin. A strayandroid.content.Contextimport fails to compile, and the unit tests run in milliseconds.- Editing a mapper in
datarecompilesdataand:app.uistays cached.
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:
// 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.
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.
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.
@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 module | Internal responsibility | Public contract |
|---|---|---|
:core-analytics | Vendor SDK initialization, batching, user consent | Analytics interface with track() |
:core-network | OkHttp/Ktor client, auth interceptors, retries | ApiClient interface |
:core-config | Remote config sync, feature flag evaluation | AppConfig interface |
:core-ui | Design system theme, typography, reusable components | Stateless 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
@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, onedomainand onedatagives 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.