Architecting Kotlin Multiplatform Solutions: Patterns for Scalable Cross-Platform Craft at Artnest

Every team starting a Kotlin Multiplatform project faces a moment of architectural choice. The decision—how to structure shared code, where to draw platform boundaries, and how to manage dependencies—shapes everything from build times to team autonomy. This guide is for developers and tech leads who want to move beyond toy examples and build a production-grade KMP solution that scales with their team and product. We walk through the decision criteria, compare three major architectural patterns, and offer concrete next steps. No fabricated statistics, no vendor pitches—just honest trade-offs and practical judgment.

Who Must Choose and By When

The architectural decision for a KMP project is most critical at two points: when the project is greenfield and when the team is about to add a second platform target. In a greenfield scenario, the temptation is to start with the simplest structure—a single shared module with platform-specific expect/actual declarations. That works for prototypes and small teams, but it can become a bottleneck as the codebase grows. The second inflection point often goes unnoticed: when a second platform is added, the shared module suddenly needs to accommodate divergent platform behaviors. Teams that deferred architectural decisions then face a painful refactor.

We recommend making a deliberate architectural choice before writing the first line of shared business logic. The decision should be revisited after the first major feature is delivered and again when the team grows beyond five developers. At Artnest, we see teams that delay this choice often end up with a 'big ball of mud' in the shared module, where platform-specific code leaks through expect/actual declarations and testability suffers. The cost of refactoring later is typically 3–5 times the effort of getting it right early, based on anecdotal evidence from multiple team reports.

Another factor is the release cadence. If your team ships weekly, a modular architecture that allows independent feature development and testing is almost mandatory. Monthly releases can tolerate more centralized structure. The key is to align the architecture with the team's velocity and the number of platform-specific features. A good rule of thumb: if more than 30% of your shared module's code is inside expect/actual blocks, it's time to consider a more structured pattern.

Signs You Should Decide Now

You need an architectural decision today if any of these apply: your shared module has grown beyond 10 files, you have more than two platform targets, or you are onboarding a new developer who needs to understand the code structure. Waiting until these conditions become painful usually means the refactor will block feature delivery for at least a sprint.

Option Landscape: Three Approaches for KMP Architecture

We focus on three architectural patterns that have proven effective in production KMP projects. These are not the only possibilities, but they represent the most common choices teams make after evaluating their constraints. Each pattern has a different trade-off between simplicity, testability, and scalability.

Shared Module with Platform Delegates

This is the default pattern suggested by the official KMP documentation. You create a single shared module containing business logic, data models, and repository interfaces. Platform-specific implementations are provided via expect/actual declarations or dependency injection. The pattern is straightforward to set up: a few Gradle modules, a handful of expect functions, and you're running on both platforms. However, as the project grows, the shared module becomes a single point of coupling. Changes to one feature can ripple across the entire module, and testing requires platform-specific test runners.

Clean Architecture with Use-Case Layers

Inspired by Robert C. Martin's Clean Architecture, this pattern introduces layers: domain (entities and use cases), data (repositories and data sources), and presentation (view models or state holders). Each layer depends only on the layer directly below it, and dependencies point inward. For KMP, this means the domain layer is pure Kotlin, the data layer uses expect/actual for platform-specific storage or networking, and the presentation layer is platform-specific. This pattern enforces separation of concerns and makes the domain layer highly testable with unit tests. The downside is boilerplate: you need interfaces for every repository, data source, and use case, and the initial setup time is higher.

Feature-First Modularization

This pattern organizes code by feature rather than by layer. Each feature (e.g., login, search, profile) is its own Gradle module with its own domain, data, and presentation sub-packages. Features communicate through shared interfaces or an event bus. This pattern scales well for large teams because each feature can be developed, tested, and versioned independently. The main challenge is managing inter-feature dependencies and avoiding circular dependencies. It also requires a more sophisticated build system and a clear dependency management strategy, such as using a dependency injection framework like Koin or Kodein.

Comparison Criteria: How to Evaluate Patterns

To choose among these patterns, teams should evaluate them against a consistent set of criteria. We use five criteria that cover the most common pain points in KMP projects: testability, team scalability, build iteration speed, platform flexibility, and onboarding complexity. Each criterion is weighted differently depending on the team's context.

Testability refers to how easily you can write unit tests for business logic without running on a device. Clean Architecture excels here because the domain layer has no platform dependencies. Feature-first modularization also scores high because each feature can be tested in isolation. The shared module pattern requires mocking platform delegates, which is possible but more cumbersome.

Team scalability measures how well the architecture supports multiple developers working in parallel. Feature-first modularization wins because teams can own entire features. Clean Architecture allows parallel work by layer, but layers are often interdependent. The shared module pattern becomes a bottleneck as the team grows, since all developers modify the same module.

Build iteration speed is critical for productivity. Shared module builds are fast initially but slow down as the module grows. Feature-first modularization enables incremental builds—only changed features need recompilation. Clean Architecture sits in the middle: layer changes can trigger cascading recompilation if dependencies are not well-managed.

Platform flexibility indicates how easy it is to add a new platform target (e.g., watchOS, web). The shared module pattern requires new expect/actual declarations for each platform, which can be tedious. Clean Architecture and feature-first modularization isolate platform-specific code in the data layer, making it easier to add platforms.

Onboarding complexity is the time it takes for a new developer to become productive. The shared module pattern has the lowest learning curve. Clean Architecture requires understanding layer abstractions, and feature-first modularization requires knowledge of the module dependency graph.

Weighting the Criteria

For a startup with a small team and a single product, we recommend prioritizing onboarding complexity and build iteration speed—shared module or Clean Architecture may be best. For a mature team with multiple features and platforms, prioritize testability and team scalability—feature-first modularization is often worth the initial investment.

Trade-offs Table: Structured Comparison

The table shows that no pattern dominates across all criteria. The shared module pattern is the easiest to start with but becomes painful as the project grows. Clean Architecture offers a good balance for medium-sized teams that value testability. Feature-first modularization is the most scalable but requires upfront investment in module setup and dependency management.

A common mistake is to assume that feature-first modularization is always better. In practice, teams with fewer than five developers often find the module management overhead outweighs the benefits. The key is to match the pattern to the team size and the expected growth rate. We recommend starting with Clean Architecture if you anticipate moderate growth, and only moving to feature-first when the team exceeds eight developers or the shared module exceeds 50 files.

When to Avoid Each Pattern

Shared module pattern should be avoided if you have more than two platform targets or if your team is distributed across time zones (merge conflicts become frequent). Clean Architecture is not ideal if your team is small and needs to ship quickly—the boilerplate slows down initial development. Feature-first modularization is overkill for a prototype or a single-feature app.

Implementation Path After the Choice

Once you've selected a pattern, the next step is to implement it systematically. We outline a general path that applies to all patterns, with specific adjustments for each.

Step 1: Define Module Boundaries

Start by listing the features or layers you need. For Clean Architecture, create three Gradle modules: `domain`, `data`, and `presentation` (the latter is platform-specific). For feature-first, create one module per feature (e.g., `feature-login`, `feature-search`). For shared module, you only need one shared module, but consider splitting it into sub-packages early.

Step 2: Set Up Dependency Injection

Use a DI framework like Koin or Kodein to manage dependencies across modules. This is especially important for Clean Architecture and feature-first patterns. Define modules for each layer or feature, and ensure that platform-specific bindings are provided in the app module. Avoid using expect/actual for DI—it's better to inject platform implementations from the app module.

Step 3: Write the Domain Layer First

For any pattern, start with the pure Kotlin domain layer (entities, use cases, repository interfaces). This is the heart of your business logic and should have zero platform dependencies. Test it thoroughly with unit tests using a standard JVM test runner. This step alone will catch many design issues early.

Step 4: Implement Platform-Specific Data Sources

Create expect/actual declarations for platform-specific APIs like networking, database, or file storage. Use the repository pattern to abstract these behind interfaces. In Clean Architecture, these implementations live in the data module. In feature-first, they live within the feature module's data package.

Step 5: Connect the Presentation Layer

The presentation layer (ViewModels, Composables, SwiftUI views) is platform-specific. Use a shared ViewModel pattern if your UI framework supports it (e.g., with KMP ViewModel for Android and iOS). For feature-first, each feature module provides its own ViewModel and UI components.

Step 6: Set Up CI and Testing Pipeline

Configure your CI to run unit tests on all modules and integration tests on the shared module. Use the KMP test runner for expect/actual tests. For feature-first, ensure that each feature module can be tested independently. This step is often skipped, but it's critical for maintaining quality as the codebase grows.

Risks If You Choose Wrong or Skip Steps

Choosing an architectural pattern that doesn't fit your team or product can lead to several negative outcomes. The most common is over-engineering: adopting feature-first modularization for a two-person project adds unnecessary complexity and slows down development. The team may become frustrated and abandon the pattern, leading to a messy codebase.

Another risk is under-engineering: sticking with a shared module pattern as the team grows leads to tight coupling and merge conflicts. We've seen cases where a shared module with 30+ files becomes a 'god module' that every developer modifies, causing frequent build breaks and long integration times. The team then has to spend weeks refactoring, during which feature delivery stalls.

Skipping the domain layer is a common mistake. Teams often put business logic directly in ViewModels or platform-specific code, making it impossible to unit test. This leads to bugs that only surface on a specific platform, and fixing them requires running the app on a device, which slows down the feedback loop. We strongly recommend writing the domain layer first, even if the pattern you chose doesn't explicitly require it.

Another risk is poor dependency management. In feature-first modularization, circular dependencies between features can break the build. This often happens when two features need to share a common type. The solution is to extract shared types into a separate 'core' module, but teams sometimes resist this because it adds another module. Without it, the build becomes fragile.

Finally, neglecting platform-specific testing can lead to runtime crashes. Expect/actual declarations are a powerful tool, but they can hide platform differences. For example, an actual implementation for iOS might use a different threading model than Android, causing a race condition that only appears in production. We recommend writing platform-specific integration tests for each actual implementation.

How to Recover from a Wrong Choice

If you realize your architecture isn't working, don't panic. Start by identifying the pain points: is it build time, testability, or team coordination? Then, plan a gradual migration. For example, if you're moving from shared module to Clean Architecture, start by extracting the domain layer into its own module. Do this incrementally over several sprints, not in a single massive refactor. Communicate the plan to the team and get buy-in before starting.

Mini-FAQ: Common Questions and Pitfalls

How do I handle shared navigation in a feature-first architecture?

Navigation is often platform-specific, but you can define navigation routes in a shared module. Each feature module registers its routes, and the app module wires them together. Use a navigation graph that is built at runtime from the registered routes. This keeps features decoupled while allowing deep linking and cross-feature navigation.

Should I use expect/actual for dependency injection?

No. Expect/actual is best for platform-specific APIs like file I/O or network stacks. For DI, use a framework like Koin and provide platform-specific bindings in the app module. This keeps your DI configuration in one place and avoids scattered expect/actual declarations.

What's the biggest mistake teams make with Clean Architecture in KMP?

The biggest mistake is making the domain layer too thick. The domain layer should contain only business logic and use cases, not data transformation or repository implementations. When teams put too much logic in the domain, they end up with platform dependencies leaking through interfaces. Keep the domain layer lean and focused on pure decision-making.

How do I manage shared models across features?

Create a 'core' module for shared models, utilities, and common interfaces. This module should have no dependencies on features or platforms. Every feature module can depend on core, but core should not depend on any feature. This prevents circular dependencies and keeps the shared types clean.

When should I add a new module?

Add a new module when a set of files has a clear responsibility and is likely to change independently from the rest of the codebase. A good rule of thumb: if you have more than 10 files in a package, consider extracting them into a module. Also, if two teams need to work on the same area without stepping on each other's toes, a module boundary helps.

Recommendation Recap Without Hype

There is no one-size-fits-all architecture for Kotlin Multiplatform. The right pattern depends on your team size, the number of platforms, and your tolerance for initial complexity. For small teams (1–3 developers) targeting two platforms, the shared module pattern with a clean package structure is often sufficient. For medium teams (4–8 developers) who value testability and plan to add more platforms, Clean Architecture provides a solid foundation. For large teams (8+ developers) with multiple features and platforms, feature-first modularization offers the best scalability.

Whichever pattern you choose, start with a strong domain layer, use dependency injection to manage platform dependencies, and invest in a good CI pipeline. Avoid over-engineering early, but don't ignore architectural debt—plan to revisit your choice after the first major feature and again when the team grows. The goal is not to build the perfect architecture from day one, but to choose a pattern that can evolve with your project. At Artnest, we've seen teams succeed with all three patterns when they apply them with discipline and adapt them to their context. The key is to make the decision consciously, document it, and revisit it regularly.

Your next move: pick one pattern from this guide, sketch a module structure for your current project, and discuss it with your team in your next planning session. Then implement the domain layer first, test it, and iterate.