kmm-architecture | cc-mobile-kmm

Stats

Actions

Tags

kmm-architecture | cc-mobile-kmm

KMM architecture

The three layers, inside `commonMain`

presentation  — ViewModels, UiState/UiEvent/UiAction.  (Runs on both platforms)
      ↓
   domain     — Pure Kotlin. Models, repository interfaces, use cases.
      ↑
    data      — Repository implementations. Ktor clients, SQLDelight DAOs, mappers.

Dependency rule: presentation → domain ← data. Same as the native Android and iOS setups. The domain layer imports only Foundation-equivalent Kotlin + coroutines + kotlinx-* (serialization, datetime).

Source-set decision tree

When adding code, ask:

Does it compile on both JVM and Native with only kotlinx-* dependencies? → commonMain.
Does it need a JVM-only library (OkHttp, Room, Android Context)? → androidMain.
Does it need an Apple framework (Foundation, UIKit, Security for Keychain)? → iosMain.
Does a single narrow operation differ per platform (like getting a HttpClient engine)? → expect/actual.
Does a wider surface differ per platform (a KeyValueStore, a CryptoProvider)? → interface in commonMain, implementations in platform source sets, bound via Koin.

Prefer the higher-numbered options only when the lower ones don't fit. commonMain-first.

`expect` / `actual` vs. interface + Koin

Use expect / actual when:

The surface is small (one or two functions).
There's no reasonable common implementation.
The caller wouldn't benefit from swapping the implementation (it's truly platform-fixed).

// commonMain
internal expect fun platformHttpEngine(): HttpClientEngine

// androidMain
internal actual fun platformHttpEngine(): HttpClientEngine = OkHttp.create()

// iosMain
internal actual fun platformHttpEngine(): HttpClientEngine = Darwin.create()

Use an interface + Koin when:

The surface has multiple methods.
Tests need to substitute a fake.
The abstraction is useful even within a single platform (e.g. a KeyValueStore with in-memory, file-backed, and encrypted variants).

// commonMain/domain
interface KeyValueStore {
    suspend fun getString(key: String): String?
    suspend fun putString(key: String, value: String)
    suspend fun remove(key: String)
}

// androidMain
class DataStoreKeyValueStore(private val dataStore: DataStore<Preferences>) : KeyValueStore { ... }

// iosMain
class NSUserDefaultsKeyValueStore : KeyValueStore { ... }

What goes where

Layer	`commonMain`	`androidMain`	`iosMain`
Domain models	✓
Use cases	✓
Repository interfaces	✓
Repository impls	✓ (when using `HttpClient` + SQLDelight)	Android-specific impls only	iOS-specific impls only
DTOs (`@Serializable`)	✓
Mappers	✓
Ktor `HttpClient` config	✓	Platform engine (OkHttp)	Platform engine (Darwin)
SQLDelight schema	✓	`SqlDriver` (Android driver)	`SqlDriver` (Native driver)
ViewModels	✓
Koin modules	core modules common; platform-specific as needed	`androidModule` (binds `Context`, `SharedPreferences`, etc.)	`iosModule` (binds Darwin-specific impls)
Navigation		✓ (Navigation-Compose)	✓ (`NavigationStack` in Swift)
UI		✓ (Jetpack Compose)	✓ (SwiftUI)

Feature skeleton (for a new feature called `orders`)

shared/src/commonMain/kotlin/com/example/app/feature/orders/
├── domain/
│   ├── model/Order.kt
│   ├── model/OrderId.kt            # value class
│   ├── repository/OrderRepository.kt
│   └── usecase/GetOrderUseCase.kt
├── data/
│   ├── remote/OrderApi.kt
│   ├── remote/OrderDto.kt
│   ├── mapper/OrderMapper.kt
│   ├── repository/OrderRepositoryImpl.kt
│   └── di/orderDataModule.kt
└── presentation/orders/
    ├── OrderUiState.kt
    ├── OrderUiEvent.kt
    ├── OrderAction.kt
    └── OrderViewModel.kt

shared/src/commonTest/kotlin/com/example/app/feature/orders/
├── domain/usecase/GetOrderUseCaseTest.kt
├── data/mapper/OrderMapperTest.kt
├── data/repository/OrderRepositoryImplTest.kt   # uses Ktor MockEngine
└── presentation/OrderViewModelTest.kt

ViewModel reaches for both platforms

A shared ViewModel extends androidx.lifecycle.ViewModel (multiplatform-ready):

class OrderViewModel(
    private val getOrder: GetOrderUseCase,
) : ViewModel() {
    private val _state = MutableStateFlow<OrderUiState>(OrderUiState.Loading)
    val state: StateFlow<OrderUiState> = _state.asStateFlow()

    private val _events = Channel<OrderUiEvent>(Channel.BUFFERED)
    val events: Flow<OrderUiEvent> = _events.receiveAsFlow()

    fun onAction(action: OrderAction) { ... }
}

Android collects state in a Composable via viewModel.state.collectAsStateWithLifecycle() and sends actions with viewModel::onAction.
iOS wraps the ViewModel in a @Observable Swift class that subscribes to state and exposes Swift-friendly properties. See kmm-ios-interop skill.

Layer checklist for a new feature