Android Clean Architecture

1---2name: android-clean-architecture3description: Clean Architecture patterns for Android and Kotlin Multiplatform projects — module structure, dependency rules, UseCases, Repositories, and data layer patterns.4origin: ECC5---6 7# Android Clean Architecture8 9Clean Architecture patterns for Android and KMP projects. Covers module boundaries, dependency inversion, UseCase/Repository patterns, and data layer design with Room, SQLDelight, and Ktor.10 11## When to Activate12 13- Structuring Android or KMP project modules14- Implementing UseCases, Repositories, or DataSources15- Designing data flow between layers (domain, data, presentation)16- Setting up dependency injection with Koin or Hilt17- Working with Room, SQLDelight, or Ktor in a layered architecture18 19## Module Structure20 21### Recommended Layout22 23```24project/25├── app/                  # Android entry point, DI wiring, Application class26├── core/                 # Shared utilities, base classes, error types27├── domain/               # UseCases, domain models, repository interfaces (pure Kotlin)28├── data/                 # Repository implementations, DataSources, DB, network29├── presentation/         # Screens, ViewModels, UI models, navigation30├── design-system/        # Reusable Compose components, theme, typography31└── feature/              # Feature modules (optional, for larger projects)32    ├── auth/33    ├── settings/34    └── profile/35```36 37### Dependency Rules38 39```40app → presentation, domain, data, core41presentation → domain, design-system, core42data → domain, core43domain → core (or no dependencies)44core → (nothing)45```46 47**Critical**: `domain` must NEVER depend on `data`, `presentation`, or any framework. It contains pure Kotlin only.48 49## Domain Layer50 51### UseCase Pattern52 53Each UseCase represents one business operation. Use `operator fun invoke` for clean call sites:54 55```kotlin56class GetItemsByCategoryUseCase(57    private val repository: ItemRepository58) {59    suspend operator fun invoke(category: String): Result<List<Item>> {60        return repository.getItemsByCategory(category)61    }62}63 64// Flow-based UseCase for reactive streams65class ObserveUserProgressUseCase(66    private val repository: UserRepository67) {68    operator fun invoke(userId: String): Flow<UserProgress> {69        return repository.observeProgress(userId)70    }71}72```73 74### Domain Models75 76Domain models are plain Kotlin data classes — no framework annotations:77 78```kotlin79data class Item(80    val id: String,81    val title: String,82    val description: String,83    val tags: List<String>,84    val status: Status,85    val category: String86)87 88enum class Status { DRAFT, ACTIVE, ARCHIVED }89```90 91### Repository Interfaces92 93Defined in domain, implemented in data:94 95```kotlin96interface ItemRepository {97    suspend fun getItemsByCategory(category: String): Result<List<Item>>98    suspend fun saveItem(item: Item): Result<Unit>99    fun observeItems(): Flow<List<Item>>100}101```102 103## Data Layer104 105### Repository Implementation106 107Coordinates between local and remote data sources:108 109```kotlin110class ItemRepositoryImpl(111    private val localDataSource: ItemLocalDataSource,112    private val remoteDataSource: ItemRemoteDataSource113) : ItemRepository {114 115    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {116        return runCatching {117            val remote = remoteDataSource.fetchItems(category)118            localDataSource.insertItems(remote.map { it.toEntity() })119            localDataSource.getItemsByCategory(category).map { it.toDomain() }120        }121    }122 123    override suspend fun saveItem(item: Item): Result<Unit> {124        return runCatching {125            localDataSource.insertItems(listOf(item.toEntity()))126        }127    }128 129    override fun observeItems(): Flow<List<Item>> {130        return localDataSource.observeAll().map { entities ->131            entities.map { it.toDomain() }132        }133    }134}135```136 137### Mapper Pattern138 139Keep mappers as extension functions near the data models:140 141```kotlin142// In data layer143fun ItemEntity.toDomain() = Item(144    id = id,145    title = title,146    description = description,147    tags = tags.split("|"),148    status = Status.valueOf(status),149    category = category150)151 152fun ItemDto.toEntity() = ItemEntity(153    id = id,154    title = title,155    description = description,156    tags = tags.joinToString("|"),157    status = status,158    category = category159)160```161 162### Room Database (Android)163 164```kotlin165@Entity(tableName = "items")166data class ItemEntity(167    @PrimaryKey val id: String,168    val title: String,169    val description: String,170    val tags: String,171    val status: String,172    val category: String173)174 175@Dao176interface ItemDao {177    @Query("SELECT * FROM items WHERE category = :category")178    suspend fun getByCategory(category: String): List<ItemEntity>179 180    @Upsert181    suspend fun upsert(items: List<ItemEntity>)182 183    @Query("SELECT * FROM items")184    fun observeAll(): Flow<List<ItemEntity>>185}186```187 188### SQLDelight (KMP)189 190```sql191-- Item.sq192CREATE TABLE ItemEntity (193    id TEXT NOT NULL PRIMARY KEY,194    title TEXT NOT NULL,195    description TEXT NOT NULL,196    tags TEXT NOT NULL,197    status TEXT NOT NULL,198    category TEXT NOT NULL199);200 201getByCategory:202SELECT * FROM ItemEntity WHERE category = ?;203 204upsert:205INSERT OR REPLACE INTO ItemEntity (id, title, description, tags, status, category)206VALUES (?, ?, ?, ?, ?, ?);207 208observeAll:209SELECT * FROM ItemEntity;210```211 212### Ktor Network Client (KMP)213 214```kotlin215class ItemRemoteDataSource(private val client: HttpClient) {216 217    suspend fun fetchItems(category: String): List<ItemDto> {218        return client.get("api/items") {219            parameter("category", category)220        }.body()221    }222}223 224// HttpClient setup with content negotiation225val httpClient = HttpClient {226    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }227    install(Logging) { level = LogLevel.HEADERS }228    defaultRequest { url("https://api.example.com/") }229}230```231 232## Dependency Injection233 234### Koin (KMP-friendly)235 236```kotlin237// Domain module238val domainModule = module {239    factory { GetItemsByCategoryUseCase(get()) }240    factory { ObserveUserProgressUseCase(get()) }241}242 243// Data module244val dataModule = module {245    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }246    single { ItemLocalDataSource(get()) }247    single { ItemRemoteDataSource(get()) }248}249 250// Presentation module251val presentationModule = module {252    viewModelOf(::ItemListViewModel)253    viewModelOf(::DashboardViewModel)254}255```256 257### Hilt (Android-only)258 259```kotlin260@Module261@InstallIn(SingletonComponent::class)262abstract class RepositoryModule {263    @Binds264    abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository265}266 267@HiltViewModel268class ItemListViewModel @Inject constructor(269    private val getItems: GetItemsByCategoryUseCase270) : ViewModel()271```272 273## Error Handling274 275### Result/Try Pattern276 277Use `Result<T>` or a custom sealed type for error propagation:278 279```kotlin280sealed interface Try<out T> {281    data class Success<T>(val value: T) : Try<T>282    data class Failure(val error: AppError) : Try<Nothing>283}284 285sealed interface AppError {286    data class Network(val message: String) : AppError287    data class Database(val message: String) : AppError288    data object Unauthorized : AppError289}290 291// In ViewModel — map to UI state292viewModelScope.launch {293    when (val result = getItems(category)) {294        is Try.Success -> _state.update { it.copy(items = result.value, isLoading = false) }295        is Try.Failure -> _state.update { it.copy(error = result.error.toMessage(), isLoading = false) }296    }297}298```299 300## Convention Plugins (Gradle)301 302For KMP projects, use convention plugins to reduce build file duplication:303 304```kotlin305// build-logic/src/main/kotlin/kmp-library.gradle.kts306plugins {307    id("org.jetbrains.kotlin.multiplatform")308}309 310kotlin {311    androidTarget()312    iosX64(); iosArm64(); iosSimulatorArm64()313    sourceSets {314        commonMain.dependencies { /* shared deps */ }315        commonTest.dependencies { implementation(kotlin("test")) }316    }317}318```319 320Apply in modules:321 322```kotlin323// domain/build.gradle.kts324plugins { id("kmp-library") }325```326 327## Anti-Patterns to Avoid328 329- Importing Android framework classes in `domain` — keep it pure Kotlin330- Exposing database entities or DTOs to the UI layer — always map to domain models331- Putting business logic in ViewModels — extract to UseCases332- Using `GlobalScope` or unstructured coroutines — use `viewModelScope` or structured concurrency333- Fat repository implementations — split into focused DataSources334- Circular module dependencies — if A depends on B, B must not depend on A335 336## References337 338See skill: `compose-multiplatform-patterns` for UI patterns.339See skill: `kotlin-coroutines-flows` for async patterns.