I've seen this play out in dozens of professional projects: a developer decides to modularize their Kotlin project and creates a single module called :common or :core. At first, it feels organized. But six months later, that :common module has become a "junk drawer." It contains everything from database entities and network wrappers to date formatting utilities and UI constants.

The misconception here is that modularization is about grouping "shared" code into one place. In reality, that approach creates a hidden monolith. If your :feature-login module depends on :common just to get a User data class, it's now also dragging in the entire Room database dependency and the Retrofit configuration from that same common module. You aren't actually decoupling your code; you're just moving the mess to a different folder. This kills your build times because a tiny change in a utility class triggers a re-compile of every single module in your app.

The "Put it in Common" Trap vs. Strategic Granularity

Instead of one giant core, you want to split your modules by responsibility and stability. Think about the "E-commerce" app we've been discussing in previous lessons. Instead of a :common module, we should split it into smaller, focused pieces:

• :core-models: Just the POJOs/Data classes. No logic, no dependencies.
• :core-network: The OkHttp and Retrofit configuration.
• :core-database: The Room setup and DAOs.

Now, your :feature-catalog module can depend on :core-models and :core-network without ever knowing that a database even exists. This is how you actually achieve a fast build and a clean architecture.

Confusing 'implementation' with 'api' in Multi-Module Gradle

Once you have these modules, you'll run into a frustrating Gradle error: you've added a dependency to Module A, and Module A depends on Module B, but you can't access that dependency in Module B. You'll be tempted to just add the dependency to every single module. Don't do that.

The secret is the difference between implementation and api. When you use implementation, the dependency is private to that module. This is what you should use 90% of the time to keep your build graph lean.

// Inside :core-network build.gradle.kts
dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
}

If :app depends on :core-network, it cannot see OkHttp. That's a good thing. But what if :core-network has a function that returns an OkHttp Response object? Now, :app needs to know what a Response is to call that function. This is where api comes in.

// Inside :core-network build.gradle.kts
dependencies {
    // Now any module depending on :core-network also gets OkHttp transitively
    api("com.squareup.okhttp3:okhttp:4.12.0")
}

I always tell my juniors: use implementation by default. Only switch to api if the library's types are part of the module's public interface (i.e., they appear in the return types or parameters of your public functions). If you use api everywhere, you're back to the "junk drawer" problem, where a version bump in one library forces the entire project to recompile.

📋 Practical Task

Refactoring a Monolithic 'Core' into Domain and Data Modules

You are working on a project with a bloated :core module. This module currently contains both the Product data model (which is used everywhere) and the ProductApi interface (which requires Retrofit). Your goal is to fix the dependency leak so that feature modules don't pull in Retrofit just to use the Product model.

Requirements:

1. Create two new modules: :core-domain and :core-data.
2. Move the Product data class into :core-domain.
3. Move the ProductApi interface and Retrofit implementation into :core-data.
4. Configure the :core-data build file to depend on :core-domain using implementation.
5. Configure the :core-data build file to use api for the Retrofit dependency, as the ProductApi returns Retrofit Call objects.
6. Update the :app module's dependencies so it depends on both :core-domain and :core-data.

Verification: Ensure that a class in :core-domain cannot import any Retrofit classes, while a class in :app can access both the Product model and the ProductApi.