Mastering Clean Architecture in Android: Use Cases, Repositories, and Data Sources

Spaghetti code kills productivity. When your ViewModel is 1,000 lines long and handles API calls, database queries, and business validation, you aren't building a feature—you're building a maintenance nightmare. To scale an app, you must separate what the app does from how it gets the data.

As a solo developer managing over 20 apps, I cannot afford to spend weeks refactoring a single feature because I decided to switch from Retrofit to Ktor or Room to Realm. I need a system where the core business logic remains untouched regardless of the external tools I use. That is the promise of Clean Architecture.

The Structural Problem: The "Fat ViewModel" Trap

Most Android developers start with a simple MVVM approach: View $\rightarrow$ ViewModel $\rightarrow$ Repository. On paper, this works. In practice, the ViewModel becomes a dumping ground for logic. It starts by calling a repository, but then it needs to filter a list, format a date, and check a user permission. Suddenly, your ViewModel is doing three different jobs.

When business logic lives in the ViewModel, it is tied to the Android Lifecycle. You cannot easily unit test it without mocking the ViewModel's internal state, and you certainly cannot reuse that logic in another part of the app.

Clean Architecture solves this by introducing a strict hierarchy of dependencies. The rule is simple: Dependencies point inwards. The inner layers (Domain) know nothing about the outer layers (Data/UI).

The Domain Layer: The Heart of the App

The Domain layer is the most critical part of your application. It contains your Entities (plain data classes) and your Use Cases (Interactors). This layer must be written in pure Kotlin—no

android.*

A Use Case represents a single, atomic action a user can take. Instead of a

UserRepository

GetUserDetailsUseCase

UpdateUserProfileUseCase

This granularity prevents the "God Class" syndrome. If the logic for calculating a user's loyalty points changes, you only touch the

CalculateLoyaltyPointsUseCase

// Domain Layer: Pure Kotlin
data class User(val id: String, val name: String, val email: String)

interface UserRepository {
    suspend fun getUserById(userId: String): User
}

class GetUserUseCase(private val userRepository: UserRepository) {
    suspend operator fun invoke(userId: String): Result<User> {
        return try {
            val user = userRepository.getUserById(userId)
            if (user.name.isBlank()) {
                Result.failure(Exception("User name cannot be empty"))
            } else {
                Result.success(user)
            }
        } catch (e: Exception) {
            Result.failure(e)
        }
    }
}

[!IMPORTANT] By using the

code Copy

operator fun invoke

, you can call the use case as a function:

code Copy

getUserUseCase(userId)

. This makes the code highly readable and encapsulates the logic perfectly.

The Data Layer: Repositories and Data Sources

While the Domain layer defines what needs to happen via interfaces, the Data layer implements how it happens. This is where we split the responsibility further into Repositories and Data Sources.

The Repository

The Repository acts as the mediator. It doesn't know if the data comes from a REST API, a local SQLite database, or a hardcoded mock for testing. Its only job is to coordinate the Data Sources to provide the Domain layer with the requested Entity.

The Data Source

Data Sources are the low-level implementations. You should have a

RemoteDataSource

LocalDataSource

// Data Layer: Implementation
class UserRemoteDataSource(private val api: UserApiService) {
    suspend fun fetchUser(id: String): UserDto = api.getUser(id)
}

class UserLocalDataSource(private val dao: UserDao) {
    suspend fun saveUser(user: UserEntity) = dao.insertUser(user)
    suspend fun getUser(id: String): UserEntity? = dao.getUserById(id)
}

class UserRepositoryImpl(
    private val remoteDataSource: UserRemoteDataSource,
    private val localDataSource: UserLocalDataSource
) : UserRepository {
    override suspend fun getUserById(userId: String): User {
        // Simple caching logic: check local first, then remote
        val localUser = localDataSource.getUser(userId)
        return if (localUser != null) {
            localUser.toDomain()
        } else {
            val remoteUser = remoteDataSource.fetchUser(userId)
            localDataSource.saveUser(remoteUser.toEntity())
            remoteUser.toDomain()
        }
    }
}

[!TIP] Always use Mapper classes or extension functions (like

code Copy

.toDomain()

and

code Copy

.toEntity()

) to convert data between layers. Never let a

code Copy

UserDto

(network model) leak into your ViewModel.

Integrating with the Presentation Layer

Now that we have a clean pipeline, the ViewModel becomes thin. Its only responsibility is to manage the UI state and trigger the Use Case. It doesn't care where the data comes from or how it's validated; it simply observes the result.

Using Kotlin StateFlow and Coroutines, the flow looks like this:

UI

ViewModel

UseCase

Repository

DataSource

API/DB

When the user clicks a button, the ViewModel calls the Use Case. The Use Case executes the business logic and returns a result. The ViewModel then updates a

StateFlow

[!WARNING] Avoid the temptation to inject the Repository directly into the ViewModel for "simplicity." While it saves a few lines of code now, it bypasses the business logic layer and leads back to the "Fat ViewModel" problem as the app grows.

Comparison: Traditional MVVM vs. Clean Architecture

To visualize the impact, let's compare how a simple "Fetch User" feature is handled in both patterns.

Handling Dependencies with Hilt

Managing this many layers manually would lead to a massive, unmanageable

ServiceLocator

UserRepository

UserRepositoryImpl

@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
    @Binds
    @Singleton
    abstract fun bindUserRepository(
        userRepositoryImpl: UserRepositoryImpl
    ): UserRepository
}

By using

@Binds

UserRepository

UserRepositoryImpl

[!NOTE] For solo developers, Hilt significantly reduces the boilerplate of passing dependencies through constructors across five different layers.

Scaling for the Future

When you build 20+ apps, you realize that patterns are more important than frameworks. Today we use Jetpack Compose; tomorrow there might be something else. Today we use Room; tomorrow we might move to a NoSQL cloud solution.

Clean Architecture is an insurance policy. By isolating the business logic in Use Cases and abstracting data access through Repositories and Data Sources, you ensure that your core intellectual property—the rules that make your app valuable—is not hostage to a third-party library.

The initial overhead of creating more files (one file per Use Case) feels like "over-engineering" at first. However, the moment you need to implement a complex feature—like a multi-step onboarding flow that requires data from three different APIs and a local database—you will be grateful that your logic is segmented into small, testable, and independent units.

Key Takeaways

• Extract Business Logic: Move any logic involving validation, filtering, or calculation out of the ViewModel and into dedicated Use Case classes.
• Strict Layering: Ensure the Domain layer has zero dependencies on Android frameworks or data libraries. Use interfaces to define data requirements and implement them in the Data layer.
• Separate Data Sources: Split your Repository into
  code Copy

  RemoteDataSource

  and
  code Copy

  LocalDataSource

  to implement caching and offline-first capabilities without cluttering your business logic.
• Map Your Models: Create separate data models for the Network (
  code Copy

  Dto

  ), Database (
  code Copy

  Entity

  ), and Domain (
  code Copy

  DomainModel

  ). Use mappers to convert between them to prevent external API changes from breaking your UI.