Kotlin Multiplatform (KMP) is becoming an increasingly popular approach for building applications that target multiple platforms while allowing developers to share Kotlin code.
However, understanding Kotlin Multiplatform architecture is important before starting a real-world KMP project.
Unlike traditional single-platform Android development, a KMP project can contain code that is shared across platforms as well as code that is specific to Android, iOS, or another target.
The architecture determines:
- Which code should be shared
- Which code should remain platform-specific
- How Android and iOS communicate with shared code
- Where API logic should live
- Where business logic should live
- How repositories should be organized
- How platform-specific implementations work
- How dependencies are managed
- How the application can remain maintainable as it grows
In this guide, you’ll learn Kotlin Multiplatform architecture from the basics, including commonMain, androidMain, iosMain, source sets, shared modules, expect/actual, repositories, networking, databases, dependency injection, UI architecture, and best practices.
What Is Kotlin Multiplatform Architecture?
Kotlin Multiplatform architecture is the way a multiplatform application separates shared code from platform-specific code.
A simple KMP architecture can look like this:
Application
|
+----------+----------+
| |
Android iOS
| |
Android UI iOS UI
| |
+----------+----------+
|
Shared KMP
|
+---------------+---------------+
| | |
Domain Data Models
| | |
+---------------+---------------+
|
API / Database
The most important concept is:
Share common application logic, but keep platform-specific functionality where it belongs.
This gives developers the flexibility to build native or shared user interfaces while sharing business and data logic.
Why Is KMP Architecture Important?
Without a clear architecture, a multiplatform application can become difficult to maintain.
Imagine an application with:
20 API endpoints
15 screens
10 business rules
Authentication
Local database
Push notifications
Payment integration
Analytics
If everything is mixed together, the project can quickly become difficult to understand.
A well-designed architecture separates responsibilities.
For example:
UI
↓
Presentation
↓
Domain
↓
Repository
↓
Data
↓
Network / Database
This makes the code easier to:
- Test
- Reuse
- Maintain
- Debug
- Extend
- Share between platforms
Basic Kotlin Multiplatform Project Structure
A KMP project commonly contains multiple source sets.
A simplified structure looks like:
shared/
└── src/
├── commonMain/
├── commonTest/
├── androidMain/
├── androidUnitTest/
├── iosMain/
└── iosTest/
Each source set has a specific purpose.
What Is commonMain?
commonMain is one of the most important directories in a Kotlin Multiplatform project.
It contains code that can be shared across supported platforms.
For example:
commonMain/
├── model/
├── repository/
├── domain/
├── network/
├── database/
└── util/
Typical shared code includes:
- Data classes
- Business logic
- Repository interfaces
- API models
- Validation
- Networking
- Database logic
- Use cases
- Shared state
- Utility functions
Example:
data class User(
val id: Int,
val name: String,
val email: String
)
This model can potentially be used by both Android and iOS.
What Is commonTest?
commonTest is used for tests that can run against shared multiplatform code.
For example:
commonTest/
└── UserValidatorTest.kt
Suppose you have:
class UserValidator {
fun isValidEmail(email: String): Boolean {
return email.contains("@")
}
}
You can test the business logic in common code.
class UserValidatorTest {
@Test
fun validEmail() {
val validator = UserValidator()
assertTrue(
validator.isValidEmail("user@example.com")
)
}
}
The exact test configuration depends on the project setup and target platforms.
What Is androidMain?
androidMain contains Android-specific implementation code.
For example:
androidMain/
├── platform/
├── database/
├── permissions/
└── services/
Use this source set when your implementation requires Android-specific APIs or dependencies.
Examples include:
- Android Context
- Android permissions
- Android-specific SDKs
- Android services
- Android storage APIs
- Android-specific integrations
Conceptually:
commonMain
|
↓
Shared interface
|
↓
androidMain
|
↓
Android implementation
What Is iosMain?
iosMain contains iOS-specific Kotlin implementation code.
For example:
iosMain/
├── platform/
├── services/
├── permissions/
└── storage/
It can be used when shared code needs an implementation that depends on iOS-specific functionality.
Conceptually:
commonMain
|
↓
Shared interface
|
↓
iosMain
|
↓
iOS implementation
What Is androidUnitTest?
This source set is used for Android-specific unit tests.
Use it when the code being tested depends on Android APIs or Android-specific implementations.
What Is iosTest?
iosTest is used for iOS-specific tests.
It can contain tests for functionality that depends on iOS-specific implementations.
Understanding Source Sets
Source sets are one of the fundamental concepts of KMP.
Think of them like separate areas for different levels of code sharing.
commonMain
↓
Everyone can use it
androidMain
↓
Android only
iosMain
↓
iOS only
A simplified hierarchy:
commonMain
/ \
/ \
androidMain iosMain
↓ ↓
Android iOS
Shared Code Architecture
A common KMP architecture might look like this:
shared/
│
├── src/
│ ├── commonMain/
│ │ ├── data/
│ │ ├── domain/
│ │ ├── model/
│ │ └── presentation/
│ │
│ ├── androidMain/
│ │ └── platform/
│ │
│ └── iosMain/
│ └── platform/
The shared module becomes the central location for reusable application logic.
Recommended KMP Layered Architecture
For larger applications, a layered architecture is often useful.
A simple structure is:
Presentation
↓
Domain
↓
Data
↓
Network / Database
Let’s understand each layer.
1. Presentation Layer
The presentation layer is responsible for UI-related state and presentation logic.
Depending on your architecture, it may contain:
- ViewModels
- UI state
- StateFlow
- Presentation models
- UI events
For example:
data class UserUiState(
val isLoading: Boolean = false,
val users: List<User> = emptyList(),
val error: String? = null
)
The UI observes the state and displays it.
2. Domain Layer
The domain layer contains business rules.
For example:
Login
Shopping Cart
Order Calculation
Discount
Validation
Subscription
Permissions Logic
A use case could look like:
class CalculateCartTotal {
operator fun invoke(
products: List<Product>
): Double {
return products.sumOf {
it.price
}
}
}
This logic is independent of Android and iOS.
Therefore, it is an excellent candidate for commonMain.
3. Data Layer
The data layer manages application data.
It can include:
- Repositories
- API services
- Database access
- Cache
- Data sources
- DTOs
Example:
interface UserRepository {
suspend fun getUsers(): List<User>
}
The repository interface can live in shared code.
4. Network Layer
The network layer communicates with your backend.
A typical architecture is:
UI
↓
ViewModel
↓
Use Case
↓
Repository
↓
API Client
↓
Backend
This allows the networking implementation to remain separate from the UI.
KMP Repository Pattern
The Repository pattern is commonly useful in multiplatform applications.
For example:
interface ProductRepository {
suspend fun getProducts(): List<Product>
}
An implementation can then use a network or database data source.
class ProductRepositoryImpl(
private val api: ProductApi
) : ProductRepository {
override suspend fun getProducts(): List<Product> {
return api.getProducts()
}
}
The UI does not need to know where the data comes from.
Why Use Repositories in KMP?
Repositories provide an abstraction between application logic and data sources.
For example:
Repository
/ \
/ \
Network Cache
| |
API Local DB
This makes it easier to change the underlying data source later.
KMP Data Flow
A typical request might travel through the application like this:
User taps button
↓
UI event
↓
ViewModel
↓
Use Case
↓
Repository
↓
API
↓
Backend
↓
Repository
↓
ViewModel
↓
UI State
↓
Screen updates
This separation is especially useful for larger applications.
Kotlin Multiplatform and expect / actual
Sometimes shared code needs functionality that is different on every platform.
For example:
Get device information
Android and iOS may require different APIs.
You can define a common declaration:
expect fun getPlatformName(): String
Then provide platform implementations.
Android:
actual fun getPlatformName(): String {
return "Android"
}
iOS:
actual fun getPlatformName(): String {
return "iOS"
}
The shared code can call:
val platformName = getPlatformName()
without directly depending on the platform implementation.
When Should You Use expect / actual?
Use platform-specific implementations when functionality cannot reasonably be shared.
Examples:
- Device information
- Platform-specific storage
- Native SDK integration
- Platform-specific permissions
- Certain OS APIs
- Platform-specific services
However, don’t use expect / actual for everything.
If a functionality can be shared cleanly, keep it in commonMain.
Alternative: Interfaces and Dependency Injection
Another approach is to define an interface in shared code.
For example:
interface Logger {
fun log(message: String)
}
Then Android and iOS can provide implementations.
This approach can be especially useful when using dependency injection.
Conceptually:
Logger Interface
|
+----------+----------+
↓ ↓
AndroidLogger IOSLogger
This keeps shared code independent of platform implementations.
Dependency Injection in KMP
Dependency injection can help provide platform-specific implementations to shared code.
For example:
Shared Repository
↓
Logger
↓
+------+------+
| |
Android iOS
Logger Logger
A dependency injection framework or manual dependency injection can be used depending on the project’s requirements.
The key principle is:
Shared code should depend on abstractions rather than concrete platform implementations.
KMP Networking Architecture
A scalable networking architecture can look like:
API Layer
↓
API Client
↓
Repository
↓
Use Case
↓
ViewModel
↓
UI
For example:
interface UserApi {
suspend fun getUsers(): List<User>
}
The implementation can use a multiplatform-compatible HTTP client.
KMP With Coroutines
Kotlin Coroutines are useful for asynchronous operations.
For example:
class UserRepository(
private val api: UserApi
) {
suspend fun getUsers(): List<User> {
return api.getUsers()
}
}
A ViewModel can then launch the operation.
viewModelScope.launch {
val users = repository.getUsers()
}
The exact scope and ViewModel implementation depend on the multiplatform architecture and framework being used.
KMP With Flow and StateFlow
Kotlin Flow can be useful for reactive application state.
For example:
private val _state =
MutableStateFlow(UserUiState())
val state: StateFlow<UserUiState> =
_state
The UI can observe changes.
Conceptually:
Repository
↓
Flow
↓
ViewModel
↓
StateFlow
↓
UI
This can help maintain predictable state management.
KMP Database Architecture
For applications that require offline functionality, a shared database layer can be useful.
A typical structure:
Repository
|
+---- Remote Data Source
|
+---- Local Data Source
|
↓
Database
The repository decides whether data should come from:
- Network
- Local cache
- Database
- Combination of sources
This architecture can support offline-first applications.
KMP Offline-First Architecture
An offline-first application might follow:
UI
↓
ViewModel
↓
Repository
/ \
↓ ↓
Local Remote
Database API
| |
+-----+-----+
↓
Synchronization
The exact implementation depends on the application’s requirements.
KMP UI Architecture
There are multiple approaches to UI.
Approach 1: Native UI
Use:
Android → Jetpack Compose
iOS → SwiftUI
Architecture:
Shared KMP
/ \
↓ ↓
Android UI iOS UI
This provides strong platform-specific UI experiences.
Approach 2: Shared UI
Use Compose Multiplatform where appropriate.
Architecture:
Shared Compose UI
↓
Android + iOS
This can increase code sharing.
Approach 3: Hybrid UI
Some parts can be shared while certain screens or components remain platform-specific.
Shared UI
+
Native Components
+
Platform APIs
This can be useful when an application has both common and highly platform-specific requirements.
KMP MVVM Architecture
MVVM can be used in a KMP application.
A simplified structure:
View
↓
ViewModel
↓
Repository
↓
Data Source
For example:
Android UI ──────┐
↓
Shared ViewModel
↓
Repository
↓
API
iOS UI ──────────┘
The exact way ViewModels are shared depends on the chosen architecture and UI framework.
KMP Clean Architecture
For larger projects, Clean Architecture can be combined with KMP.
A common structure is:
Presentation
↓
Domain
↓
Data
The Domain layer can contain:
Entities
Use Cases
Business Rules
Interfaces
The Data layer can contain:
Repository Implementations
Remote Data Sources
Local Data Sources
DTOs
Mappers
The Presentation layer can contain:
ViewModels
UI State
Events
Example KMP Clean Architecture
shared/
│
├── commonMain/
│
│ ├── presentation/
│ │ ├── UserViewModel.kt
│ │ └── UserUiState.kt
│ │
│ ├── domain/
│ │ ├── User.kt
│ │ ├── UserRepository.kt
│ │ └── GetUsersUseCase.kt
│ │
│ └── data/
│ ├── UserRepositoryImpl.kt
│ ├── UserApi.kt
│ └── UserDto.kt
│
├── androidMain/
│ └── platform/
│
└── iosMain/
└── platform/
This is only an example. Your actual structure should reflect your project’s size and requirements.
KMP Feature-Based Architecture
For large applications, feature-based organization can be better than putting everything into generic folders.
For example:
commonMain/
│
├── auth/
│ ├── data/
│ ├── domain/
│ └── presentation/
│
├── home/
│ ├── data/
│ ├── domain/
│ └── presentation/
│
├── products/
│ ├── data/
│ ├── domain/
│ └── presentation/
│
└── profile/
├── data/
├── domain/
└── presentation/
This approach makes large applications easier to navigate.
KMP Multi-Module Architecture
Large projects may use multiple modules.
For example:
Project
│
├── app-android
├── app-ios
│
├── shared
│
├── core-network
├── core-database
├── core-common
│
└── feature-auth
However, don’t create dozens of modules unnecessarily.
Start simple and introduce modules when they solve a real organizational or architectural problem.
Shared Module vs Platform Modules
A KMP application can be thought of as:
Shared Module
|
+------------+------------+
| |
Android App iOS App
| |
Android-specific iOS-specific
code code
The shared module contains reusable code.
The application modules contain platform-specific application setup and integration.
What Should Go Into commonMain?
Good candidates include:
Business Logic
Pricing
Validation
Cart calculations
Authentication rules
Order calculations
Models
User
Product
Order
Category
Address
Networking
API interfaces
DTOs
Repository logic
Database
When using a multiplatform-compatible database solution.
State
UiState
StateFlow
Shared state
Utilities
Only when the utility is genuinely platform-independent.
What Should Go Into androidMain?
Examples include:
Android Context
Android Services
Android-specific SDKs
Android permissions
Android storage
Android APIs
Don’t put generic business logic here just because the application currently runs on Android.
What Should Go Into iosMain?
Examples include:
iOS frameworks
iOS-specific SDKs
iOS platform APIs
iOS-specific storage
iOS-specific services
Keep these implementations isolated from shared business rules whenever possible.
Common KMP Architecture Mistakes
1. Sharing Everything
Trying to force every piece of code into commonMain can make the architecture unnecessarily complicated.
Share what is genuinely common.
2. Putting Business Logic in UI
Avoid:
UI
↓
API
↓
Business Logic
Prefer:
UI
↓
ViewModel
↓
Use Case
↓
Repository
↓
API
3. Too Much Platform Code
If most business logic ends up in:
androidMain
iosMain
you aren’t getting the full benefit of KMP.
Look for opportunities to move platform-independent logic into commonMain.
4. Overusing expect / actual
Don’t create expect / actual declarations for functionality that can easily be implemented in common code.
Use platform-specific mechanisms only when there is a genuine platform difference.
5. Poor Dependency Boundaries
Avoid allowing shared business logic to depend directly on Android-specific APIs.
Instead:
Domain
↓
Interface
↓
Platform Implementation
6. Creating Too Many Modules
A project with many tiny modules can become harder to understand.
Start with a clean shared module and introduce additional modules as the project grows.
Best Practices for KMP Architecture
1. Keep Business Logic Platform Independent
The domain layer should ideally know nothing about Android or iOS.
Domain
↓
Platform Independent
2. Use Interfaces
Define contracts in shared code.
interface Analytics {
fun track(event: String)
}
Then provide platform implementations.
3. Keep UI Separate When Appropriate
If Android and iOS require significantly different UI experiences, don’t force shared UI simply to increase code-sharing percentage.
4. Use a Repository Layer
Repositories create a clean boundary between business logic and data sources.
5. Keep API Models Separate From Domain Models
For larger projects, avoid coupling your business logic directly to backend DTOs.
A common structure is:
DTO
↓
Mapper
↓
Domain Model
↓
UI
6. Test Shared Logic
Business rules should be tested in shared code whenever possible.
7. Avoid Premature Abstraction
Don’t create complex abstractions before you actually need them.
A simple architecture is often better for small applications.
Example: KMP E-Commerce Architecture
Imagine an e-commerce application.
The shared module could contain:
commonMain/
│
├── auth/
├── products/
├── cart/
├── orders/
├── profile/
│
├── network/
├── database/
├── models/
└── utils/
Android:
androidMain/
├── notifications/
├── permissions/
└── payment/
iOS:
iosMain/
├── notifications/
├── permissions/
└── payment/
The result:
Shared KMP
|
+--------------+--------------+
| | |
Auth Products Orders
| | |
+--------------+--------------+
|
Android + iOS
Example: KMP Authentication Flow
A shared authentication flow might be:
Login Screen
↓
Login Event
↓
Auth ViewModel
↓
Login Use Case
↓
Auth Repository
↓
API
↓
Authentication Response
↓
Save Session
↓
Update UI State
Android and iOS can consume the same authentication business logic.
Example: KMP Product Flow
Product Screen
↓
Product ViewModel
↓
Get Products Use Case
↓
Product Repository
↓
Remote API
↓
Product DTO
↓
Mapper
↓
Product Model
↓
UI State
↓
Product Screen
This is a clean and scalable approach.
KMP Architecture and Dependency Direction
One of the most important architectural rules is controlling dependency direction.
Prefer:
Presentation
↓
Domain
↓
Data
rather than:
Presentation
↓
Data
↓
Domain
The domain should contain the application’s core business rules without depending on platform-specific implementations.
How KMP Architecture Helps Maintenance
Suppose the company changes its discount rule.
Without shared logic:
Android → Update
iOS → Update
There is a risk that the implementations become different.
With shared logic:
Shared Business Rule
↓
Android
iOS
The core rule can be changed in one location.
This can improve consistency and reduce duplicated maintenance.
Is KMP Architecture the Same for Every Project?
No.
There is no single mandatory KMP architecture.
A small project may only need:
commonMain
androidMain
iosMain
A larger application might use:
Presentation
Domain
Data
Network
Database
Features
Core Modules
Platform Modules
The architecture should match the project’s complexity.
Simple KMP Architecture for Beginners
If you’re just starting, don’t overcomplicate your project.
Start with:
shared/
│
├── commonMain/
│ ├── model/
│ ├── repository/
│ ├── network/
│ └── domain/
│
├── androidMain/
│
└── iosMain/
Then add:
presentation/
database/
features/
as the project grows.
Recommended KMP Architecture
For a medium-to-large production application, a practical architecture can look like:
Android App
|
Android UI
|
|
Shared KMP
|
+-----------------+-----------------+
| | |
Presentation Domain Data
| | |
ViewModels Use Cases Repositories
UI State Business Rules |
| | +------+------+
| | | |
| | Network Database
| | | |
+-----------------+----------+-------------+
|
Platform Layer
/ \
Android iOS
This provides a strong separation of responsibilities while keeping shared code reusable.
Kotlin Multiplatform Architecture Checklist
Before starting your KMP application, ask:
Shared Code
- Can this logic run on every target?
- Does it depend on Android?
- Does it depend on iOS?
- Can it live in
commonMain?
Platform Code
- Does this require a native API?
- Should this implementation live in
androidMain? - Should this implementation live in
iosMain?
Architecture
- Is business logic separated from UI?
- Is networking separated from repositories?
- Are domain models separated from DTOs?
- Are platform dependencies isolated?
Testing
- Can this logic be tested in
commonTest? - Does the platform implementation need its own tests?
Frequently Asked Questions
What is Kotlin Multiplatform architecture?
Kotlin Multiplatform architecture is a way of organizing shared and platform-specific Kotlin code so that business and data logic can be reused while platform-specific functionality remains separate.
What is commonMain in KMP?
commonMain contains Kotlin code that can be shared across supported platforms.
What is androidMain?
androidMain contains Android-specific Kotlin code and implementations.
What is iosMain?
iosMain contains iOS-specific Kotlin code and implementations.
Can I share business logic in KMP?
Yes. Business logic is one of the strongest use cases for Kotlin Multiplatform.
Can I share API code?
Yes. Multiplatform-compatible networking libraries can be used to create shared API and repository layers.
Can I share ViewModels?
Shared ViewModels can be used depending on the architecture and UI framework you choose. However, the integration with Android and iOS UI should be designed carefully.
Can KMP share UI?
Yes. UI can remain native, or technologies such as Compose Multiplatform can be used to share UI across supported targets.
What is expect and actual in KMP?
expect declares a common API while actual provides platform-specific implementations.
Should everything go into commonMain?
No. Only platform-independent functionality should generally be placed there. Platform-specific functionality belongs in the appropriate platform source set.
Conclusion
Kotlin Multiplatform architecture is built around a simple but powerful idea:
Share what is common and keep what is platform-specific.
The core source sets are:
commonMain
↓
Shared Kotlin code
androidMain
↓
Android-specific code
iosMain
↓
iOS-specific code
For larger applications, you can organize shared code into layers:
Presentation
↓
Domain
↓
Data
↓
Network / Database
This architecture allows you to share business logic, networking, models, repositories, validation, and other common functionality while still using native Android and iOS capabilities.
The most important KMP architecture principles are:
- Keep business logic platform-independent
- Use
commonMainfor shared code - Keep Android-specific code in
androidMain - Keep iOS-specific code in
iosMain - Use interfaces and dependency injection for platform implementations
- Use
expect/actualwhen appropriate - Separate presentation, domain, and data responsibilities
- Avoid unnecessary abstractions
- Test shared business logic
- Share UI only when it makes sense for the project
A good KMP architecture doesn’t try to maximize the percentage of shared code.
Instead, it tries to maximize useful code sharing without sacrificing maintainability, native capabilities, or a good developer experience.
Once you understand commonMain, androidMain, iosMain, shared modules, repositories, and platform-specific implementations, you’ll have a solid foundation for building production-ready Kotlin Multiplatform applications.
