Kotlin Multiplatform (KMP): AI-Optimized Technical Reference

Status and Stability

• Stable Release: November 2023 after years of beta
• Official Support: Google officially supports KMP for business logic sharing (May 2024)
• Governance: Kotlin Foundation oversees language development, JetBrains maintains toolchain
• Production Ready: Yes, but with significant operational overhead

Core Architecture

Project Structure

commonMain/     # Shared business logic
androidMain/    # Android-specific implementations  
iosMain/        # iOS-specific implementations

expect/actual Mechanism

// commonMain - declare interface
expect fun getCurrentPlatform(): String

// androidMain - provide implementation
actual fun getCurrentPlatform(): String = "Android"

// iosMain - provide implementation  
actual fun getCurrentPlatform(): String = "iOS"

Implementation Approaches

Option 1: Logic Sharing + Native UI

• Code Sharing: 50-80% business logic reuse
• UI: Platform-native interfaces maintained
• User Experience: Indistinguishable from native apps
• Best For: Teams prioritizing platform conventions

Option 2: Full Compose Multiplatform

• Code Sharing: 80-95% including UI
• UI: Shared Compose interface (stable for iOS as of May 2025)
• User Experience: Slightly Android-biased on iOS
• Best For: Teams prioritizing development speed over platform feel

Performance Characteristics

Runtime Performance

• Android: JVM bytecode (native performance)
• iOS: Native machine code via LLVM compilation
• No Overhead: No JavaScript bridge or interpretation layers
• Memory: Uses platform-native memory management

Build Performance Critical Issues

Platform	Pure Native Build	KMP Build	Performance Impact
Android	2-3 minutes	2-3 minutes	No significant change
iOS	3-4 minutes	8-12 minutes	2-3x slower
CI/CD	Standard	Requires optimization	Budget 2-3 days setup

iOS Build Failures:

• LLVM compilation errors on machines with <16GB RAM
• Xcode updates break KMP builds with cryptic linker errors
• CocoaPods integration produces "duplicate symbols for architecture x86_64"
• Gradle sync can take 10+ minutes on bad days

Production Library Ecosystem

Networking

• Ktor: HTTP client, more verbose than Retrofit but works everywhere
• Apollo Kotlin: GraphQL support, stable multiplatform implementation
• Avoid: Attempting to make Retrofit multiplatform

Database

• SQLDelight: Type-safe SQL, production-ready today
• Room KMP: Coming but not production-ready yet
• Migration: SQLDelight generates type-safe code, reduces database bugs

Dependency Injection

• Koin: Works without annotation processors, less complex than Dagger
• Avoid: Dagger/Hilt (Android-specific annotation processing)

Utilities

• Napier: Cross-platform logging that doesn't crash on iOS
• Kotlinx.serialization: JSON parsing more reliable than Gson for KMP
• Coroutines: Async programming across platforms (iOS threading requires careful handling)

Real-World Production Cases

Netflix: Internal Tools Only

• Scope: Studio apps for production crews, NOT consumer streaming app
• Code Sharing: ~50% business logic
• Strategy: Lower-risk internal tools before customer-facing apps
• Scale: Thousands of lines of shared business logic

McDonald's: Payment Processing

• Scale: 6.5 million monthly payments
• Code Sharing: Started with payments, expanded to full app
• Team Impact: Merged separate iOS/Android teams into unified mobile team
• Build Cost: 3x longer iOS build times, required CI/CD optimization

Forbes: Media Application

• Code Sharing: 80% of app logic
• Challenge: Platform-specific article rendering harder than expected
• Learning: Reading experiences deeply tied to platform conventions
• UI Strategy: Preserved native UI for better user experience

Team Requirements and Resource Planning

Minimum Team Composition

• Size: 4-5 developers minimum
• Skills Required:
  • Strong Android/Kotlin expertise
  • iOS development knowledge
  • Dedicated "KMP expert" for build issues
• Time Investment: 2-3 months initial setup and learning

Learning Curve by Background

Developer Background	Learning Time	Key Challenges
Android Developer	2-3 weeks	Multiplatform Gradle configuration
iOS Developer	4-6 weeks	Kotlin language, Gradle build system
Full Team	2-3 months	Integration, debugging shared code

When NOT to Use KMP

• Team smaller than 4 developers
• No Android/Kotlin expertise
• Cannot afford 2-3x iOS build time increases
• App mostly UI with minimal business logic
• Need rapid feature delivery without setup overhead

Critical Debugging Challenges

iOS Debugging Pain Points

When shared business logic crashes on iOS:

1. Reproduce in iOS simulator
2. Locate corresponding Kotlin code
3. Interpret generated Objective-C headers (shared_module_kn_suspend_impl)
4. Debug through platform boundaries with stack traces showing "native code"

Common Error Scenarios

• NSInvalidArgumentException: expect/actual implementations don't match
• LLVM ERROR: out of memory: Insufficient RAM during iOS compilation
• Xcode linker errors: KMP builds break after Xcode updates
• Threading issues: iOS handles background threads differently than Android

Debugging Tools

• SKIE: Makes Kotlin APIs feel more natural from Swift
• TouchLab debugging guide: Platform-specific debugging strategies
• Kotlin/Native memory manager: Essential for iOS crash debugging

Migration Patterns

Successful Patterns

1. Start Small: Single feature (user preferences, API calls)
2. Payment-First: Critical business logic with high shared value
3. Green Field: New projects avoid legacy integration issues

Migration Timeline

• Month 1: Project setup, build configuration, team training
• Month 2: First shared feature implementation
• Month 3: Debugging, CI/CD optimization, team workflow establishment
• Ongoing: Feature migration, build optimization

Resource Requirements

Infrastructure Needs

• Build Machines: More powerful machines for iOS compilation
• CI/CD: 2-3 days setup, ongoing optimization required
• Development: macOS required for iOS development (no changes from native)

Operational Costs

• Build Time: 2-3x increase for iOS builds
• Team Training: 2-3 months productivity ramp-up
• Tooling: Additional complexity in Gradle configuration
• Maintenance: Dedicated KMP expert for build issues

Technical Decision Matrix

Use Case	KMP Fit	Alternative	Decision Factors
Android company expanding to iOS	Excellent	Native iOS team	Team size >4, strong Android expertise
Complex business logic duplication	Good	Code generation	Shared logic >30% of codebase
Rapid MVP development	Poor	Flutter/React Native	Time to market priority
Platform-specific user experiences	Moderate	Native development	UI complexity vs logic complexity

This technical reference provides the operational intelligence needed for informed KMP adoption decisions, including realistic timelines, resource requirements, and failure scenarios not covered in marketing materials.