Jetpack Compose

┌─────────────────────────────────────────────────────────┐
│                Compose Multiplatform (CMP)              │
│              (Shared declarative UI layer)              │
├─────────────────────────────────────────────────────────┤
│               Kotlin Multiplatform (KMP)                │
│         (Shared business logic, data, domain)           │
├───────────┬──────────────┬──────────────┬───────────────┤
│  Kotlin/  │ Kotlin/      │ Kotlin/      │ Kotlin/       │
│  JVM      │ Native       │ Wasm         │ JVM           │
│ (Android) │ (iOS/macOS)  │ (Web)        │ (Desktop)     │
└───────────┴──────────────┴──────────────┴───────────────┘

commonMain Compose Code
         │
         ├── Android
         │     └── Jetpack Compose Runtime
         │           └── Android RenderNode / Canvas API
         │                 └── Skia (via Android's internal pipeline)
         │
         ├── iOS
         │     └── Skiko (Kotlin/Native bindings to Skia)
         │           └── Metal GPU API
         │                 └── CAMetalLayer embedded in UIView
         │
         ├── Desktop (JVM)
         │     └── Skiko
         │           └── OpenGL / DirectX / Metal (OS-dependent)
         │
         └── Web
               └── Kotlin/Wasm + Skia compiled to WebAssembly
                     └── HTML <canvas> element

// commonMain — declares the contract
expect fun currentTimeMillis(): Long

// androidMain - Android implementation
actual fun currentTimeMillis(): Long = System.currentTimeMillis()

// iosMain - iOS implementation (using Kotlin/Native platform APIs)
actual fun currentTimeMillis(): Long = 
    NSDate().timeIntervalSince1970.toLong() * 1000

root/
├── gradle/
│   └── libs.versions.toml          ← Centralized version catalog
│
├── build-logic/                    ← Convention plugins
│   └── src/main/kotlin/
│       ├── CmpLibraryPlugin.kt     ← Shared Gradle config for library modules
│       └── CmpAppPlugin.kt         ← Shared Gradle config for app modules
│
├── core/
│   ├── domain/                     ← Pure Kotlin: entities, use cases, repository interfaces
│   │   └── src/commonMain/
│   ├── data/                       ← Repository implementations, network, cache
│   │   └── src/commonMain/
│   ├── ui-components/              ← Shared design system, reusable composables
│   │   └── src/commonMain/
│   ├── navigation/                 ← Route definitions, navigation contracts
│   │   └── src/commonMain/
│   └── testing/                    ← Shared test utilities and fakes
│       └── src/commonTest/
│
├── features/
│   ├── product-list/
│   │   └── src/commonMain/
│   ├── product-detail/
│   │   └── src/commonMain/
│   └── cart/
│       └── src/commonMain/
│
├── composeApp/                     ← Platform entry points + DI wiring
│   └── src/
│       ├── commonMain/             ← App-level navigation graph, DI setup
│       ├── androidMain/            ← Android Activity, platform DI modules
│       ├── iosMain/                ← iOS entry point called from Swift
│       └── wasmJsMain/             ← Web entry point
│
└── iosApp/                         ← Xcode project
    └── iosApp/
        ├── ContentView.swift       ← Hosts CMP root composable
        └── iOSApp.swift            ← App lifecycle; calls into Kotlin layer

// build-logic/src/main/kotlin/CmpLibraryPlugin.kt
// Convention plugin applied to all shared library modules

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

plugins {
    id("com.android.library")
    kotlin("multiplatform")
    id("org.jetbrains.compose")
    id("org.jetbrains.kotlin.plugin.compose")
}

kotlin {
    androidTarget {
        compilerOptions {                    // Note: kotlinOptions {} is deprecated
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "SharedModule"
            isStatic = true
            // Static frameworks are required for proper Kotlin/Native
            // memory management with Swift ARC interop
        }
    }

    @OptIn(ExperimentalWasmDsl::class)
    wasmJs {
        browser()
        binaries.executable()
    }

    sourceSets {
        commonMain.dependencies {
            implementation(compose.runtime)
            implementation(compose.foundation)
            implementation(compose.material3)
            implementation(compose.ui)
            implementation(compose.components.resources)
            implementation(libs.lifecycle.viewmodel.compose)      // Multiplatform ViewModel
            implementation(libs.lifecycle.runtime.compose)        // collectAsStateWithLifecycle
            implementation(libs.navigation.compose)               // Multiplatform nav
            implementation(libs.kotlinx.coroutines.core)
            implementation(libs.koin.compose)                     // DI
        }

        androidMain.dependencies {
            implementation(libs.androidx.activity.compose)
            implementation(libs.kotlinx.coroutines.android)       // Provides Dispatchers.Main on Android
        }

        iosMain.dependencies {
            implementation(libs.kotlinx.coroutines.core)
            // Note: kotlinx-coroutines-core for Native provides
            // Dispatchers.Main via Darwin integration - requires explicit dependency
        }
        commonTest.dependencies {
            implementation(libs.kotlin.test)
            implementation(libs.kotlinx.coroutines.test)
        }
    }
}

┌─────────────────────────────────────────┐
│              UI Layer (CMP)             │
│  Composables receive UiState, emit      │
│  events/callbacks. No business logic.   │
├─────────────────────────────────────────┤
│           ViewModel Layer               │
│  Holds UiState (single StateFlow).      │
│  Orchestrates use cases. Maps domain    │
│  models to UI models.                   │
├─────────────────────────────────────────┤
│            Domain Layer                 │
│  Use cases (interactors). Pure Kotlin.  │
│  No framework dependencies.             │
├─────────────────────────────────────────┤
│             Data Layer                  │
│  Repository implementations.            │
│  Ktor for network. SQLDelight for DB.   │
│  Platform-specific data sources.        │
└─────────────────────────────────────────┘

// Correct: Single state object prevents impossible states
// and triggers exactly one recomposition per state change

sealed class ProductListUiState {
    object Loading : ProductListUiState()
    
    data class Success(
        val products: List<ProductUiModel>,
        val searchQuery: String = ""
    ) : ProductListUiState()
    
    data class Error(
        val message: String,
        val isRetryable: Boolean
    ) : ProductListUiState()
}

// UiModel - separate from domain model
// Only contains what the UI needs; formatted strings, not raw data
@Immutable  // Tells Compose compiler this is stable - critical for LazyColumn performance
data class ProductUiModel(
    val id: String,
    val name: String,
    val formattedPrice: String,    // "$12.99" not 12.99 - formatting in ViewModel, not Composable
    val description: String,
    val imageUrl: String
)

class ProductListViewModel(
    private val getProductsUseCase: GetProductsUseCase
) : ViewModel() {

private val _uiState = MutableStateFlow<ProductListUiState>(ProductListUiState.Loading)
    val uiState: StateFlow<ProductListUiState> = _uiState.asStateFlow()
    init {
        loadProducts()
    }

    fun loadProducts() {
        viewModelScope.launch {
            _uiState.value = ProductListUiState.Loading
            getProductsUseCase()
                .onSuccess { products ->
                    _uiState.value = ProductListUiState.Success(
                        products = products.map { it.toUiModel() }
                    )
                }
                .onFailure { error ->
                    _uiState.value = ProductListUiState.Error(
                        message = error.toUserFacingMessage(),
                        isRetryable = error is NetworkException
                    )
                }
        }
    }

    fun onSearchQueryChanged(query: String) {
        val currentState = _uiState.value as? ProductListUiState.Success ?: return
        _uiState.value = currentState.copy(searchQuery = query)
    }
}

// Extension to convert domain model to UI model
private fun Product.toUiModel() = ProductUiModel(
    id = id,
    name = name,
    formattedPrice = "$${"%.2f".format(price)}",
    description = description,
    imageUrl = imageUrl
)

// Anti-pattern — breaks testability and state hoisting
@Composable
fun ProductListScreen(viewModel: ProductListViewModel) {
    val uiState by viewModel.uiState.collectAsState()
    // ...
}

// Correct - state in, events out
@Composable
fun ProductListScreen(
    uiState: ProductListUiState,
    onRetry: () -> Unit,
    onSearchQueryChanged: (String) -> Unit,
    onProductClick: (String) -> Unit,   // Pass ID, not the whole object
    modifier: Modifier = Modifier        // Always accept a Modifier parameter
) {
    when (uiState) {
        is ProductListUiState.Loading -> LoadingContent(modifier)
        is ProductListUiState.Error -> ErrorContent(
            message = uiState.message,
            isRetryable = uiState.isRetryable,
            onRetry = onRetry,
            modifier = modifier
        )
        is ProductListUiState.Success -> ProductListContent(
            products = uiState.products,
            searchQuery = uiState.searchQuery,
            onSearchQueryChanged = onSearchQueryChanged,
            onProductClick = onProductClick,
            modifier = modifier
        )
    }
}

// In your navigation graph 
composable<ProductList> {
    val viewModel: ProductListViewModel = koinViewModel()
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
    // collectAsStateWithLifecycle is preferred over collectAsState —
    // it respects platform lifecycle and pauses collection when the app is backgrounded

    ProductListScreen(
        uiState = uiState,
        onRetry = viewModel::loadProducts,
        onSearchQueryChanged = viewModel::onSearchQueryChanged,
        onProductClick = { productId ->
            navController.navigate(ProductDetail(productId))
        }
    )
}

@Composable
fun SearchBar(
    query: String,                        // Lifted state — parent owns it
    onQueryChange: (String) -> Unit,
    onSearch: (String) -> Unit,
    modifier: Modifier = Modifier
) {
    // No local mutableStateOf needed — state is owned by caller
    // Only use remember for objects that are expensive to create
    val focusRequester = remember { FocusRequester() }

    OutlinedTextField(
        value = query,
        onValueChange = onQueryChange,
        modifier = modifier.focusRequester(focusRequester),
        // ...
    )
}

// For state that must survive configuration changes AND process death,
// use rememberSaveable with a Saver if the type is not primitive:
val scrollState = rememberSaveable(saver = ScrollState.Saver) { ScrollState(0) }

// Lifecycle-aware — pauses when app is in background on all platforms
val uiState by viewModel.uiState.collectAsStateWithLifecycle()

// Always-on - continues collecting even when app is backgrounded
val uiState by viewModel.uiState.collectAsState()

// core/navigation/src/commonMain/RouteDefinitions.kt

import kotlinx.serialization.Serializable

@Serializable
object ProductList                          // No-argument destination

@Serializable
data class ProductDetail(val productId: String)  // Typed argument

@Serializable
object Cart

@Serializable
data class Checkout(
    val cartId: String,
    val promoCode: String? = null           // Optional parameters supported
)

// composeApp/src/commonMain/AppNavigation.kt

@Composable
fun AppNavigation(
    navController: NavHostController = rememberNavController()
) {
    NavHost(
        navController = navController,
        startDestination = ProductList
    ) {
        composable<ProductList> {
            val viewModel: ProductListViewModel = koinViewModel()
            val uiState by viewModel.uiState.collectAsStateWithLifecycle()
            ProductListScreen(
                uiState = uiState,
                onRetry = viewModel::loadProducts,
                onSearchQueryChanged = viewModel::onSearchQueryChanged,
                onProductClick = { productId ->
                    navController.navigate(ProductDetail(productId))
                }
            )
        }

        composable<ProductDetail> { backStackEntry ->
            val route: ProductDetail = backStackEntry.toRoute()  // Type-safe extraction
            val viewModel: ProductDetailViewModel = koinViewModel(
                parameters = { parametersOf(route.productId) }
            )
            val uiState by viewModel.uiState.collectAsStateWithLifecycle()
            ProductDetailScreen(
                uiState = uiState,
                onBack = { navController.navigateUp() },
                onAddToCart = viewModel::addToCart
            )
        }

        composable<Cart> {
            val viewModel: CartViewModel = koinViewModel()
            val uiState by viewModel.uiState.collectAsStateWithLifecycle()
            CartScreen(
                uiState = uiState,
                onCheckout = { cartId ->
                    navController.navigate(Checkout(cartId))
                },
                onBack = { navController.navigateUp() }
            )
        }
    }
}

BackHandler(enabled = uiState is CheckoutUiState.InProgress) {
    // Prompt user before losing checkout progress
    showExitConfirmationDialog = true
}

// core/domain/src/commonMain/ — Define a pure interface
interface FileStorage {
    suspend fun saveFile(fileName: String, data: ByteArray): Result<Unit>
    suspend fun readFile(fileName: String): Result<ByteArray>
    suspend fun deleteFile(fileName: String): Result<Unit>
}

// core/data/src/androidMain/ - Android implementation with Context via DI
class AndroidFileStorage(
    private val context: Context    // Injected by DI framework
) : FileStorage {
    override suspend fun saveFile(fileName: String, data: ByteArray): Result<Unit> =
        runCatching {
            val file = File(context.filesDir, fileName)
            file.writeBytes(data)
        }
    override suspend fun readFile(fileName: String): Result<ByteArray> =
        runCatching {
            File(context.filesDir, fileName).readBytes()
        }
    override suspend fun deleteFile(fileName: String): Result<Unit> =
        runCatching {
            File(context.filesDir, fileName).delete()
        }
}

// core/data/src/iosMain/ - iOS implementation
class IosFileStorage : FileStorage {
    private val fileManager = NSFileManager.defaultManager
    override suspend fun saveFile(fileName: String, data: ByteArray): Result<Unit> =
        runCatching {
            val documentsDir = fileManager
                .URLsForDirectory(NSDocumentDirectory, NSUserDomainMask)
                .firstOrNull()?.path ?: error("No documents directory")
            val filePath = "$documentsDir/$fileName"
            data.toNSData().writeToFile(filePath, atomically = true)
        }
    // ... other implementations
}

// features/map/src/iosMain/ — iOS-specific file
@Composable
fun NativeMapView(
    latitude: Double,
    longitude: Double,
    modifier: Modifier = Modifier
) {
    UIKitView(
        factory = {
            MKMapView().apply {
                // Configure once on creation
                showsUserLocation = true
            }
        },
        update = { mapView ->
            // Called on recomposition when inputs change
            val region = MKCoordinateRegionMake(
                CLLocationCoordinate2DMake(latitude, longitude),
                MKCoordinateSpanMake(0.01, 0.01)
            )
            mapView.setRegion(region, animated = true)
        },
        modifier = modifier
    )
}

// Dangerous on iOS — will attempt network calls even when app is suspended
class ProductListViewModel : ViewModel() {
    init {
        viewModelScope.launch {
            // This may run after iOS has suspended your app,
            // causing unexpected behavior or battery drain
            productRepository.startPolling()
        }
    }
}

// Correct - use lifecycle-aware collection
class ProductListViewModel : ViewModel() {
    val uiState: StateFlow<ProductListUiState> = productRepository
        .productsFlow
        .map { it.toUiState() }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5_000),
            // WhileSubscribed stops the upstream flow when there are no collectors
            // (i.e., when the screen is not visible)
            initialValue = ProductListUiState.Loading
        )
}

// iosMain — observe iOS lifecycle notifications
class IosLifecycleObserver {
    private var observers: List<NSObjectProtocol> = emptyList()

    fun start(
        onBackground: () -> Unit,
        onForeground: () -> Unit
    ) {
        val center = NSNotificationCenter.defaultCenter
        observers = listOf(
            center.addObserverForName(
                name = UIApplicationDidEnterBackgroundNotification,
                `object` = null,
                queue = NSOperationQueue.mainQueue
            ) { _ -> onBackground() },
            center.addObserverForName(
                name = UIApplicationWillEnterForegroundNotification,
                `object` = null,
                queue = NSOperationQueue.mainQueue
            ) { _ -> onForeground() }
        )
    }

    fun stop() {
        observers.forEach { NSNotificationCenter.defaultCenter.removeObserver(it) }
        observers = emptyList()
    }
}

// iosApp/ContentView.swift
import SwiftUI
import ComposeApp  // The generated Kotlin framework

struct ContentView: View {
    var body: some View {
        ComposeView()
            .ignoresSafeArea(.keyboard)  // Let CMP handle keyboard insets itself
    }
}

// ComposeView wraps the Kotlin entry point
struct ComposeView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        MainViewControllerKt.MainViewController()  // Kotlin function
    }
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {}
}

// iosMain — Kotlin entry point called from Swift
fun MainViewController() = ComposeUIViewController(
    configure = {
        // Configure the Compose host here
        // For example, register platform-specific implementations
    }
) {
    // Koin DI initialization for iOS
    KoinApplication(
        application = { modules(platformModule(), sharedModule()) }
    ) {
        AppNavigation()
    }
}

// core/di/src/commonMain/ — Shared DI modules

val domainModule = module {
    factory<GetProductsUseCase> { GetProductsUseCaseImpl(get()) }
    factory<AddToCartUseCase> { AddToCartUseCaseImpl(get()) }
}

val dataModule = module {
    single<ProductRepository> { ProductRepositoryImpl(get(), get()) }
    single<CartRepository> { CartRepositoryImpl(get()) }
    single { HttpClient(/* Ktor config */) }
}

val viewModelModule = module {
    viewModel { ProductListViewModel(get()) }
    viewModel { (productId: String) -> ProductDetailViewModel(productId, get()) }
    viewModel { CartViewModel(get(), get()) }
}

// composeApp/src/androidMain/ — Android platform module
val androidPlatformModule = module {
    single<FileStorage> { AndroidFileStorage(androidContext()) }
    single<AnalyticsTracker> { FirebaseAnalyticsTracker(androidContext()) }
}

// In Android Application class:
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        startKoin {
            androidContext(this@MyApplication)
            modules(androidPlatformModule, dataModule, domainModule, viewModelModule)
        }
    }
}

// composeApp/src/iosMain/ — iOS platform module
val iosPlatformModule = module {
    single<FileStorage> { IosFileStorage() }
    single<AnalyticsTracker> { SentryAnalyticsTracker() }
}

// Called from Swift MainViewController:
fun initKoin() {
    startKoin {
        modules(iosPlatformModule, dataModule, domainModule, viewModelModule)
    }
}

// Usage in navigation — type-safe ViewModel injection
composable<ProductDetail> { backStackEntry ->
    val route: ProductDetail = backStackEntry.toRoute()
    val viewModel: ProductDetailViewModel = koinViewModel(
        parameters = { parametersOf(route.productId) }
    )
    // ...
}

@Composable
fun ProductCard(
    product: ProductUiModel,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    Card(
        onClick = onClick,
        modifier = modifier
            .fillMaxWidth()
            .semantics(mergeDescendants = true) {  // Merge child semantics into one node
                contentDescription = buildString {
                    append(product.name)
                    append(", ")
                    append(product.formattedPrice)
                    append(". ")
                    append(product.description.take(100))  // Truncate long descriptions
                }
                role = Role.Button
                onClick(label = "View details for ${product.name}") {
                    onClick()
                    true
                }
            },
        elevation = CardDefaults.cardElevation(defaultElevation = 2.dp)
    ) {
        // Card content
    }
}

// Loading states need explicit a11y announcements
@Composable
fun LoadingContent(modifier: Modifier = Modifier) {
    Box(
        modifier = modifier
            .fillMaxSize()
            .semantics { contentDescription = "Loading products, please wait" },
        contentAlignment = Alignment.Center
    ) {
        CircularProgressIndicator()
    }
}

// Register for iOS memory pressure notifications and clear image caches
// This should be done in your iosMain platform setup

class IosMemoryPressureHandler(
    private val imageLoader: ImageLoader  // Coil's ImageLoader
) {
    fun register() {
        NSNotificationCenter.defaultCenter.addObserverForName(
            name = UIApplicationDidReceiveMemoryWarningNotification,
            `object` = null,
            queue = NSOperationQueue.mainQueue
        ) { _ ->
            imageLoader.memoryCache?.clear()
            imageLoader.diskCache?.clear()
        }
    }
}

@Immutable  // Tells Compose: all properties are val and of stable types
data class ProductUiModel(
    val id: String,
    val name: String,
    val formattedPrice: String,
    val description: String,
    val imageUrl: String
)

// Without @Immutable, a data class with List<> properties will be inferred
// as unstable by the Compose compiler, causing full recomposition of every
// LazyColumn item on every parent recomposition - a major performance issue
@Immutable
data class CartUiState(
    val items: List<CartItemUiModel>,  // List<> requires @Immutable on the containing class
    val totalFormatted: String,
    val itemCount: Int
)

// In your app's build.gradle.kts
composeCompiler {
    metricsDestination = layout.buildDirectory.dir("compose-metrics")
    reportsDestination = layout.buildDirectory.dir("compose-reports")
}

// core/domain/src/commonTest/ — Pure logic tests run on all platforms

class ProductListViewModelTest {
    private val testProducts = listOf(
        Product(id = "1", name = "Widget", price = 9.99, description = "A widget", imageUrl = ""),
        Product(id = "2", name = "Gadget", price = 19.99, description = "A gadget", imageUrl = "")
    )

    @Test
    fun `loadProducts emits Success state with mapped UI models`() = runTest {
        val fakeRepository = FakeProductRepository(products = testProducts)
        val useCase = GetProductsUseCaseImpl(fakeRepository)
        val viewModel = ProductListViewModel(useCase)
        val state = viewModel.uiState.value
        assertTrue(state is ProductListUiState.Success)
        assertEquals(2, (state as ProductListUiState.Success).products.size)
        assertEquals("$9.99", state.products[0].formattedPrice)
    }

    @Test
    fun `loadProducts emits Error state on network failure`() = runTest {
        val fakeRepository = FakeProductRepository(shouldFail = true)
        val useCase = GetProductsUseCaseImpl(fakeRepository)
        val viewModel = ProductListViewModel(useCase)
        val state = viewModel.uiState.value
        assertTrue(state is ProductListUiState.Error)
        assertTrue((state as ProductListUiState.Error).isRetryable)
    }
}

// Fake repository - not a mock, avoids Mockito (JVM-only)
class FakeProductRepository(
    private val products: List<Product> = emptyList(),
    private val shouldFail: Boolean = false
) : ProductRepository {
    override suspend fun getProducts(): Result<List<Product>> = if (shouldFail) {
        Result.failure(NetworkException("Network unavailable"))
    } else {
        Result.success(products)
    }
}

// composeApp/src/androidTest/ - Android UI tests
class ProductListScreenTest {
    @get:Rule
    val composeTestRule = createComposeRule()

    @Test
    fun productList_showsLoadingIndicator_whenStateIsLoading() {
        composeTestRule.setContent {
            ProductListScreen(
                uiState = ProductListUiState.Loading,
                onRetry = {},
                onSearchQueryChanged = {},
                onProductClick = {}
            )
        }

        composeTestRule.onNodeWithContentDescription("Loading products, please wait")
            .assertIsDisplayed()
    }

    @Test
    fun productList_showsProducts_whenStateIsSuccess() {
        val products = listOf(
            ProductUiModel("1", "Widget", "$9.99", "A widget", "")
        )

        composeTestRule.setContent {
            ProductListScreen(
                uiState = ProductListUiState.Success(products),
                onRetry = {},
                onSearchQueryChanged = {},
                onProductClick = {}
            )
        }

        composeTestRule.onNodeWithText("Widget").assertIsDisplayed()
        composeTestRule.onNodeWithText("$9.99").assertIsDisplayed()
    }
}

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]
jobs:
  unit-tests:
    runs-on: macos-14  # macOS required for Kotlin/Native iOS compilation
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: 17
          distribution: temurin
      - name: Run common unit tests
        run: ./gradlew :core:domain:allTests
      - name: Run data layer tests
        run: ./gradlew :core:data:allTests
  android-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Android UI tests
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 33
          script: ./gradlew :composeApp:connectedAndroidTest
  ios-build:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
      - name: Build iOS framework
        run: ./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64
      - name: Build Xcode project
        run: |
          xcodebuild build \
            -project iosApp/iosApp.xcodeproj \
            -scheme iosApp \
            -destination 'platform=iOS Simulator,name=iPhone 15'

// composeApp/src/commonMain/ — Shared error reporting interface
interface ErrorReporter {
    fun captureException(throwable: Throwable, context: Map<String, String> = emptyMap())
    fun addBreadcrumb(category: String, message: String)
    fun setUser(userId: String)
}

// In your ViewModel base class:
abstract class BaseViewModel(
    protected val errorReporter: ErrorReporter
) : ViewModel() {
    protected fun launchWithErrorHandling(
        block: suspend CoroutineScope.() -> Unit
    ) = viewModelScope.launch {
        try {
            block()
        } catch (e: CancellationException) {
            throw e  // Never swallow CancellationException
        } catch (e: Exception) {
            errorReporter.captureException(e)
            handleError(e)
        }
    }
    protected open fun handleError(e: Exception) {}
}

// commonMain — platform-agnostic logging interface
interface AppLogger {
    fun debug(tag: String, message: String)
    fun info(tag: String, message: String)
    fun warn(tag: String, message: String, throwable: Throwable? = null)
    fun error(tag: String, message: String, throwable: Throwable? = null)
}

// androidMain
class AndroidLogger : AppLogger {
    override fun debug(tag: String, message: String) = Log.d(tag, message)
    override fun error(tag: String, message: String, throwable: Throwable?) =
        Log.e(tag, message, throwable)
    // ...
}

// iosMain
class IosLogger : AppLogger {
    override fun debug(tag: String, message: String) {
        NSLog("DEBUG [$tag]: $message")
    }
    override fun error(tag: String, message: String, throwable: Throwable?) {
        NSLog("ERROR [$tag]: $message ${throwable?.message ?: ""}")
    }
    // ...
}

// Will not compile — Android import in shared code
import android.content.Context

// Define an interface in commonMain, implement per platform
interface PlatformContext  // Marker interface or use Koin's module system

// Always use imePadding() for forms — handles iOS keyboard differently than Android
@Composable
fun FormScreen() {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .imePadding()           // Pushes content above keyboard on both platforms
            .verticalScroll(rememberScrollState())
            .padding(16.dp)
    ) {
        // Form fields
    }
}

// iosMain — MUST call this before any coroutine usage on iOS
// Without it, Dispatchers.Main may not be properly initialized

fun initCoroutines() {
    // This is handled automatically when using lifecycle-viewmodel on iOS,
    // but if you use coroutines outside of ViewModels, explicit initialization
    // may be required depending on your kotlinx-coroutines-core version
}

// Swallows coroutine cancellation — causes memory leaks and undefined behavior
try {
    val result = repository.getProducts()
} catch (e: Exception) {
    handleError(e)  // CancellationException caught here!
}

// Always rethrow CancellationException
try {
    val result = repository.getProducts()
} catch (e: CancellationException) {
    throw e  // Must propagate
} catch (e: Exception) {
    handleError(e)
}