Android Clean Architecture
Clean Architecture patterns for Android and Kotlin Multiplatform projects — module structure, dependency rules, UseCases, Repositories, and data layer patterns. Use when structuring modules, layers, or data flow in an Android or KMP project.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Android Clean Architecture when an AI agent needs a reusable SKILL.md workflow for this job: Clean Architecture patterns for Android and Kotlin Multiplatform projects — module structure, dependency rules, UseCases, Repositories, and data layer patterns. Use when structuring modules, layers, or data flow in an Android or KMP project.
When not to use it
Skip Android Clean Architecture when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/android-clean-architecture # Save SKILL.md to ~/.claude/skills/android-clean-architecture/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/android-clean-architecture/SKILL.md. For a shared project, commit the folder at .claude/skills/android-clean-architecture/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Android Clean Architecture skill for this task: Use Android Clean Architecture when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Android Clean Architecture
Clean Architecture patterns for Android and KMP projects. Covers module boundaries, dependency inversion, UseCase/Repository patterns, and data layer design with Room, SQLDelight, and Ktor.
## When to Activate
- Structuring Android or KMP project modules - Implementing UseCases, Repositories, or DataSources - Designing data flow between layers (domain, data, presentation) - Setting up dependency injection with Koin or Hilt - Working with Room, SQLDelight, or Ktor in a layered architecture
## Module Structure
### Recommended Layout
``` project/ ├── app/ # Android entry point, DI wiring, Application class ├── core/ # Shared utilities, base classes, error types ├── domain/ # UseCases, domain models, repository interfaces (pure Kotlin) ├── data/ # Repository implementations, DataSources, DB, network ├── presentation/ # Screens, ViewModels, UI models, navigation ├── design-system/ # Reusable Compose components, theme, typography └── feature/ # Feature modules (optional, for larger projects) ├── auth/ ├── settings/ └── profile/ ```
### Dependency Rules
``` app → presentation, domain, data, core presentation → domain, design-system, core data → domain, core domain → core (or no dependencies) core → (nothing) ```
**Critical**: `domain` must NEVER depend on `data`, `presentation`, or any framework. It contains pure Kotlin only.
## Domain Layer
### UseCase Pattern
Each UseCase represents one business operation. Use `operator fun invoke` for clean call sites:
```kotlin class GetItemsByCategoryUseCase( private val repository: ItemRepository ) { suspend operator fun invoke(category: String): Result<List<Item>> { return repository.getItemsByCategory(category) } }
// Flow-based UseCase for reactive streams class ObserveUserProgressUseCase( private val repository: UserRepository ) { operator fun invoke(userId: String): Flow<UserProgress> { return repository.observeProgress(userId) } } ```
### Domain Models
Domain models are plain Kotlin data classes — no framework annotations:
```kotlin 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 } ```
### Repository Interfaces
Defined in domain, implemented in data:
```kotlin interface ItemRepository { suspend fun getItemsByCategory(category: String): Result<List<Item>> suspend fun saveItem(item: Item): Result<Unit> fun observeItems(): Flow<List<Item>> } ```
## Data Layer
### Repository Implementation
Coordinates between local and remote data sources:
```kotlin 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() } } } } ```
### Mapper Pattern
Keep mappers as extension functions near the data models:
```kotlin // In data layer 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)
```kotlin @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)
```sql -- 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; ```
### Ktor Network Client (KMP)
```kotlin class ItemRemoteDataSource(private val client: HttpClient) {
suspend fun fetchItems(category: String): List<ItemDto> { return client.get("api/items") { parameter("category", category) }.body() } }
// HttpClient setup with content negotiation val httpClient = HttpClient { install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) } install(Logging) { level = LogLevel.HEADERS } defaultRequest { url("https://api.example.com/") } } ```
## Dependency Injection
### Koin (KMP-friendly)
```kotlin // Domain module val domainModule = module { factory { GetItemsByCategoryUseCase(get()) } factory { ObserveUserProgressUseCase(get()) } }
// Data module val dataModule = module { single<ItemRepository> { ItemRepositoryImpl(get(), get()) } single { ItemLocalDataSource(get()) } single { ItemRemoteDataSource(get()) } }
// Presentation module val presentationModule = module { viewModelOf(::ItemListViewModel) viewModelOf(::DashboardViewModel) } ```
### Hilt (Android-only)
```kotlin @Module @InstallIn(SingletonComponent::class) abstract class RepositoryModule { @Binds abstract fun bindItemRepository(impl: ItemRepositoryImpl): ItemRepository }
@HiltViewModel class ItemListViewModel @Inject constructor( private val getItems: GetItemsByCategoryUseCase ) : ViewModel() ```
## Error Handling
### Result/Try Pattern
Use `Result<T>` or a custom sealed type for error propagation:
```kotlin 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 }
// In ViewModel — map to UI state 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) } } } ```
## Convention Plugins (Gradle)
For KMP projects, use convention plugins to reduce build file duplication:
```kotlin // build-logic/src/main/kotlin/kmp-library.gradle.kts plugins { id("org.jetbrains.kotlin.multiplatform") }
kotlin { androidTarget() iosX64(); iosArm64(); iosSimulatorArm64() sourceSets { commonMain.dependencies { /* shared deps */ } commonTest.dependencies { implementation(kotlin("test")) } } } ```
Apply in modules:
```kotlin // domain/build.gradle.kts plugins { id("kmp-library") } ```
## Anti-Patterns to Avoid
- Importing Android framework classes in `domain` — keep it pure Kotlin - Exposing database entities or DTOs to the UI layer — always map to domain models - Putting business logic in ViewModels — extract to UseCases - Using `GlobalScope` or unstructured coroutines — use `viewModelScope` or structured concurrency - Fat repository implementations — split into focused DataSources - Circular module dependencies — if A depends on B, B must not depend on A
## References
See skill: `compose-multiplatform-patterns` for UI patterns. See skill: `kotlin-coroutines-flows` for async patterns.
Intended uses
- Use Android Clean Architecture when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.