# Kmp Architecture Best Practices

> Kotlin Multiplatform clean architecture enforcement. Use when this capability is needed.

- Skill: `tomevault-io/kmp-architecture-best-practices` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kmp-architecture-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kmp-architecture-best-practices/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kmp-architecture-best-practices

---


# KMP Architecture Rules

Activate only if commonMain exists.

## Hard Rules
- No `android.*` imports in commonMain — use expect/actual for platform APIs.
- No `java.time` in commonMain — use `kotlinx-datetime`.
- No Android ViewModel in shared code — use StateHolder pattern.
- No `Dispatchers.Main` hardcoded in commonMain — inject dispatchers.
- Use KSP for annotation processing — KAPT does not support multiplatform.
- No `freeze()` calls — the new Kotlin/Native memory model (default since 1.7.20) makes them unnecessary.
- Shared code must compile for all declared targets — never skip a target in CI.

## Core Patterns

### State Management
- commonMain: `StateHolder` class exposes `StateFlow<UiState>`.
- androidMain: `ViewModel` wraps `StateHolder`, bridges to Android lifecycle.
- iosMain: Swift class holds `StateHolder`, collects flows via `CancellableContinuation` or SKIE/KMP-NativeCoroutines.

### Dependency Injection
- Use Koin Multiplatform or manual factory pattern in commonMain.
- Platform modules provide platform-specific implementations via `actual` declarations or Koin modules.

### Source Set Hierarchy
- Use hierarchical source sets (`appleMain`, `nativeMain`, `jvmMain`) to share platform-adjacent code.
- `commonMain` → `jvmMain` → `androidMain` / `desktopMain`.
- `commonMain` → `nativeMain` → `appleMain` → `iosMain` / `macosMain`.

### Kotlin 2.0+ Considerations
- K2 compiler is default since Kotlin 2.0 — ensure libraries are K2-compatible.
- Compose Compiler is now a Gradle plugin (`org.jetbrains.kotlin.plugin.compose`) — not a separate compiler artifact.

## References
- references/project_structure.md
- references/common_libraries.md
- references/platform_apis.md
- references/testing_kmp.md
- references/dependency_injection.md

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/noloman) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->