Architecture Layers

┌─────────────────────────────────────────┐
│              UI Layer                    │
│  (Compose Screens + ViewModels)          │
├─────────────────────────────────────────┤
│           Domain Layer                   │
│  (Use Cases - optional, for reuse)       │
├─────────────────────────────────────────┤
│            Data Layer                    │
│  (Repositories + DataSources)            │
└─────────────────────────────────────────┘

Module Types

app/                    # App module - navigation, scaffolding
feature/
  ├── featurename/
  │   ├── api/          # Navigation keys (public)
  │   └── impl/         # Screen, ViewModel, DI (internal)
core/
  ├── data/             # Repositories
  ├── database/         # Room DAOs, entities
  ├── network/          # Retrofit, API models
  ├── model/            # Domain models (pure Kotlin)
  ├── common/           # Shared utilities
  ├── ui/               # Reusable Compose components
  ├── designsystem/     # Theme, icons, base components
  ├── datastore/        # Preferences storage
  └── testing/          # Test utilities

Creating a New Feature

1. Create feature:myfeature:api module with navigation key
2. Create feature:myfeature:impl module with:
   • MyFeatureScreen.kt - Composable UI
   • MyFeatureViewModel.kt - State holder
   • MyFeatureUiState.kt - Sealed interface for states
   • MyFeatureNavigation.kt - Navigation setup
   • MyFeatureModule.kt - Hilt DI module

Standard File Patterns

ViewModel Pattern

@HiltViewModel
class MyFeatureViewModel @Inject constructor(
    private val myRepository: MyRepository,
) : ViewModel() {

    val uiState: StateFlow<MyFeatureUiState> = myRepository
        .getData()
        .map { data -> MyFeatureUiState.Success(data) }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5_000),
            initialValue = MyFeatureUiState.Loading,
        )
    
    fun onAction(action: MyFeatureAction) {
        when (action) {
            is MyFeatureAction.ItemClicked -> handleItemClick(action.id)
        }
    }
}

UiState Pattern

sealed interface MyFeatureUiState {
    data object Loading : MyFeatureUiState
    data class Success(val items: List<Item>) : MyFeatureUiState
    data class Error(val message: String) : MyFeatureUiState
}

Screen Pattern

@Composable
internal fun MyFeatureRoute(
    onNavigateToDetail: (String) -> Unit,
    viewModel: MyFeatureViewModel = hiltViewModel(),
) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    MyFeatureScreen(
        uiState = uiState,
        onAction = viewModel::onAction,
        onNavigateToDetail = onNavigateToDetail,
    )
}

@Composable
internal fun MyFeatureScreen(
    uiState: MyFeatureUiState,
    onAction: (MyFeatureAction) -> Unit,
    onNavigateToDetail: (String) -> Unit,
) {
    when (uiState) {
        is MyFeatureUiState.Loading -> LoadingIndicator()
        is MyFeatureUiState.Success -> ContentList(uiState.items, onAction)
        is MyFeatureUiState.Error -> ErrorMessage(uiState.message)
    }
}

Repository Pattern

interface MyRepository {
    fun getData(): Flow<List<MyModel>>
    suspend fun updateItem(id: String, data: MyModel)
}

internal class OfflineFirstMyRepository @Inject constructor(
    private val localDataSource: MyDao,
    private val networkDataSource: MyNetworkApi,
) : MyRepository {

    override fun getData(): Flow<List<MyModel>> =
        localDataSource.getAll().map { entities ->
            entities.map { it.toModel() }
        }
    
    override suspend fun updateItem(id: String, data: MyModel) {
        localDataSource.upsert(data.toEntity())
    }
}

Key Dependencies

// Gradle version catalog (libs.versions.toml)
[versions]
kotlin = "1.9.x"
compose-bom = "2024.x.x"
hilt = "2.48"
room = "2.6.x"
coroutines = "1.7.x"

[libraries]
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }

Build Configuration

Use convention plugins in build-logic/ for consistent configuration:

• AndroidApplicationConventionPlugin - App modules
• AndroidLibraryConventionPlugin - Library modules
• AndroidFeatureConventionPlugin - Feature modules
• AndroidComposeConventionPlugin - Compose setup
• AndroidHiltConventionPlugin - Hilt setup

See gradle-setup.md for complete build configuration.

Core Principles

This skill teaches Claude to follow these key Android development principles:

1. Offline-first: Local database as source of truth, synchronized with remote data
2. Unidirectional data flow: Events flow down, data flows up (UDF pattern)
3. Reactive streams: Use Kotlin Flow for all data exposure
4. Modular by feature: Each feature is self-contained with clear API boundaries
5. Testable by design: Use interfaces and test doubles, avoid mocking frameworks

Reference Documentation

Quick Navigation

| Topic | File | Description | |-------|------|-------------| | Architecture | architecture.md | MVVM pattern, layers, repositories, use cases | | Compose UI | compose-patterns.md | Screens, state hoisting, side effects, theming | | Build Setup | gradle-setup.md | Convention plugins, version catalogs, configuration | | Modularization | modularization.md | Module types, dependencies, feature structure | | Testing | testing.md | Unit tests, UI tests, test doubles, strategies |

Architecture Overview

┌─────────────────────────────────────────┐
│              UI Layer                    │
│  (Compose Screens + ViewModels)          │
├─────────────────────────────────────────┤
│           Domain Layer                   │
│  (Use Cases - optional, for reuse)       │
├─────────────────────────────────────────┤
│            Data Layer                    │
│  (Repositories + DataSources)            │
└─────────────────────────────────────────┘

Module Types

app/                    # Application module
feature/
  ├── featurename/
  │   ├── api/          # Public navigation contracts
  │   └── impl/         # Internal implementation
core/
  ├── data/             # Repositories
  ├── database/         # Room DAOs & entities
  ├── network/          # Retrofit & API models
  ├── model/            # Domain models
  ├── ui/               # Reusable components
  ├── designsystem/     # Theme & design tokens
  └── testing/          # Test utilities

Features

Code Generation

The skill includes a Python script to generate feature modules:

python scripts/generate_feature.py settings \
  --package com.example.app \
  --path /path/to/project

This creates a complete feature module with:

• API module with navigation definitions
• Implementation module with Screen, ViewModel, UiState
• Gradle build files with proper dependencies
• Hilt dependency injection setup

Templates

Pre-configured templates for common Android project files:

• libs.versions.toml.template - Gradle version catalog
• settings.gradle.kts.template - Project settings

Standard Patterns

ViewModel Pattern

@HiltViewModel
class MyFeatureViewModel @Inject constructor(
    private val repository: MyRepository,
) : ViewModel() {
    val uiState: StateFlow<MyFeatureUiState> = repository
        .getData()
        .map { MyFeatureUiState.Success(it) }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5_000),
            initialValue = MyFeatureUiState.Loading,
        )
}

Screen Pattern

@Composable
internal fun MyFeatureRoute(
    viewModel: MyFeatureViewModel = hiltViewModel(),
) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    MyFeatureScreen(uiState = uiState)
}

Repository Pattern

interface MyRepository {
    fun getData(): Flow<List<MyModel>>
}

internal class OfflineFirstMyRepository @Inject constructor(
    private val dao: MyDao,
    private val api: MyNetworkApi,
) : MyRepository {
    override fun getData(): Flow<List<MyModel>> =
        dao.getAll().map { it.toModel() }
}

Technology Stack

This skill configures projects with:

• Language: Kotlin
• UI: Jetpack Compose
• Architecture: MVVM with UDF
• DI: Hilt
• Database: Room
• Network: Retrofit + Kotlinx Serialization
• Async: Kotlin Coroutines + Flow
• Testing: JUnit, Turbine, Compose Testing
• Build: Gradle with Convention Plugins

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Based on patterns and practices from:

• NowInAndroid by Google
• Android Architecture Guidelines
• Jetpack Compose Best Practices

Resources

• Android Developer Documentation
• NowInAndroid Repository
• Kotlin Documentation
• Jetpack Compose Pathway