android-clean-architecture

Arquitectura Limpia para Android

Patrones de Arquitectura Limpia para proyectos Android y KMP. Cubre límites de módulos, inversión de dependencias, patrones UseCase/Repository y diseño de capa de datos con Room, SQLDelight y Ktor.

Cuándo activar

• Al estructurar módulos de un proyecto Android o KMP
• Al implementar UseCases, Repositories o DataSources
• Al diseñar el flujo de datos entre capas (domain, data, presentation)
• Al configurar inyección de dependencias con Koin o Hilt
• Al trabajar con Room, SQLDelight o Ktor en una arquitectura por capas

Estructura de módulos

Diseño recomendado

project/
├── app/                  # Punto de entrada Android, cableado de DI, clase Application
├── core/                 # Utilidades compartidas, clases base, tipos de error
├── domain/               # UseCases, modelos de dominio, interfaces de repositorio (Kotlin puro)
├── data/                 # Implementaciones de repositorio, DataSources, BD, red
├── presentation/         # Pantallas, ViewModels, modelos de UI, navegación
├── design-system/        # Componentes Compose reutilizables, tema, tipografía
└── feature/              # Módulos de funcionalidad (opcional, para proyectos grandes)
    ├── auth/
    ├── settings/
    └── profile/

Reglas de dependencia

app → presentation, domain, data, core
presentation → domain, design-system, core
data → domain, core
domain → core (o sin dependencias)
core → (nada)

Crítico: domain NUNCA debe depender de data, presentation ni de ningún framework. Contiene únicamente Kotlin puro.

Capa de dominio

Patrón UseCase

Cada UseCase representa una operación de negocio. Usa operator fun invoke para puntos de llamada limpios:

class GetItemsByCategoryUseCase(
    private val repository: ItemRepository
) {
    suspend operator fun invoke(category: String): Result<List<Item>> {
        return repository.getItemsByCategory(category)
    }
}

// UseCase basado en Flow para streams reactivos
class ObserveUserProgressUseCase(
    private val repository: UserRepository
) {
    operator fun invoke(userId: String): Flow<UserProgress> {
        return repository.observeProgress(userId)
    }
}

Modelos de dominio

Los modelos de dominio son clases de datos Kotlin simples, sin anotaciones de framework:

data class Item(
    val id: String,
    val title: String,
    val description: String,
    val tags: List<String>,
    val status: Status,
    val category: String
)

enum class Status { DRAFT, ACTIVE, ARCHIVED }

Interfaces de repositorio

Definidas en domain, implementadas en data:

interface ItemRepository {
    suspend fun getItemsByCategory(category: String): Result<List<Item>>
    suspend fun saveItem(item: Item): Result<Unit>
    fun observeItems(): Flow<List<Item>>
}

Capa de datos

Implementación del repositorio

Coordina entre fuentes de datos locales y remotas:

class ItemRepositoryImpl(
    private val localDataSource: ItemLocalDataSource,
    private val remoteDataSource: ItemRemoteDataSource
) : ItemRepository {

    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {
        return runCatching {
            val remote = remoteDataSource.fetchItems(category)
            localDataSource.insertItems(remote.map { it.toEntity() })
            localDataSource.getItemsByCategory(category).map { it.toDomain() }
        }
    }

    override suspend fun saveItem(item: Item): Result<Unit> {
        return runCatching {
            localDataSource.insertItems(listOf(item.toEntity()))
        }
    }

    override fun observeItems(): Flow<List<Item>> {
        return localDataSource.observeAll().map { entities ->
            entities.map { it.toDomain() }
        }
    }
}

Patrón Mapper

Mantén los mappers como funciones de extensión cerca de los modelos de datos:

// En la capa de datos
fun ItemEntity.toDomain() = Item(
    id = id,
    title = title,
    description = description,
    tags = tags.split("|"),
    status = Status.valueOf(status),
    category = category
)

fun ItemDto.toEntity() = ItemEntity(
    id = id,
    title = title,
    description = description,
    tags = tags.joinToString("|"),
    status = status,
    category = category
)

Room Database (Android)

@Entity(tableName = "items")
data class ItemEntity(
    @PrimaryKey val id: String,
    val title: String,
    val description: String,
    val tags: String,
    val status: String,
    val category: String
)

@Dao
interface ItemDao {
    @Query("SELECT * FROM items WHERE category = :category")
    suspend fun getByCategory(category: String): List<ItemEntity>

    @Upsert
    suspend fun upsert(items: List<ItemEntity>)

    @Query("SELECT * FROM items")
    fun observeAll(): Flow<List<ItemEntity>>
}

SQLDelight (KMP)

-- Item.sq
CREATE TABLE ItemEntity (
    id TEXT NOT NULL PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT NOT NULL,
    tags TEXT NOT NULL,
    status TEXT NOT NULL,
    category TEXT NOT NULL
);

getByCategory:
SELECT * FROM ItemEntity WHERE category = ?;

upsert:
INSERT OR REPLACE INTO ItemEntity (id, title, description, tags, status, category)
VALUES (?, ?, ?, ?, ?, ?);

observeAll:
SELECT * FROM ItemEntity;

Cliente de red Ktor (KMP)

class ItemRemoteDataSource(private val client: HttpClient) {

    suspend fun fetchItems(category: String): List<ItemDto> {
        return client.get("api/items") {
            parameter("category", category)
        }.body()
    }
}

// Configuración de HttpClient con negociación de contenido
val httpClient = HttpClient {
    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
    install(Logging) { level = LogLevel.HEADERS }
    defaultRequest { url("https://api.example.com/") }
}

Inyección de dependencias

Koin (compatible con KMP)

// Módulo de dominio
val domainModule = module {
    factory { GetItemsByCategoryUseCase(get()) }
    factory { ObserveUserProgressUseCase(get()) }
}

// Módulo de datos
val dataModule = module {
    single<ItemRepository> { ItemRepositoryImpl(get(), get()) }
    single { ItemLocalDataSource(get()) }
    single { ItemRemoteDataSource(get()) }
}

// Módulo de presentación
val presentationModule = module {
    viewModelOf(::ItemListViewModel)
    viewModelOf(::DashboardViewModel)
}

Hilt (solo Android)

@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {
    @Binds
    abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository
}

@HiltViewModel
class ItemListViewModel @Inject constructor(
    private val getItems: GetItemsByCategoryUseCase
) : ViewModel()

Manejo de errores

Patrón Result/Try

Usa Result<T> o un tipo sellado personalizado para la propagación de errores:

sealed interface Try<out T> {
    data class Success<T>(val value: T) : Try<T>
    data class Failure(val error: AppError) : Try<Nothing>
}

sealed interface AppError {
    data class Network(val message: String) : AppError
    data class Database(val message: String) : AppError
    data object Unauthorized : AppError
}

// En el ViewModel — mapear a estado de UI
viewModelScope.launch {
    when (val result = getItems(category)) {
        is Try.Success -> _state.update { it.copy(items = result.value, isLoading = false) }
        is Try.Failure -> _state.update { it.copy(error = result.error.toMessage(), isLoading = false) }
    }
}

Plugins de convención (Gradle)

Para proyectos KMP, usa plugins de convención para reducir la duplicación de archivos de compilación:

// build-logic/src/main/kotlin/kmp-library.gradle.kts
plugins {
    id("org.jetbrains.kotlin.multiplatform")
}

kotlin {
    androidTarget()
    iosX64(); iosArm64(); iosSimulatorArm64()
    sourceSets {
        commonMain.dependencies { /* dependencias compartidas */ }
        commonTest.dependencies { implementation(kotlin("test")) }
    }
}

Aplicar en los módulos:

// domain/build.gradle.kts
plugins { id("kmp-library") }

Anti-patrones a evitar

• Importar clases del framework Android en domain — mantenlo como Kotlin puro
• Exponer entidades de base de datos o DTOs a la capa de UI — siempre mapea a modelos de dominio
• Poner lógica de negocio en ViewModels — extráela a UseCases
• Usar GlobalScope o corrutinas no estructuradas — usa viewModelScope o concurrencia estructurada
• Implementaciones de repositorio demasiado grandes — divide en DataSources enfocados
• Dependencias circulares entre módulos — si A depende de B, B no debe depender de A

Referencias

Consulta la habilidad: compose-multiplatform-patterns para patrones de UI. Consulta la habilidad: kotlin-coroutines-flows para patrones asíncronos.