The Elegance of Shared Layers: Advanced Kotlin Multiplatform Patterns

The Shared-Layer Promise and Its Hidden Complexity

Kotlin Multiplatform offers an alluring vision: write business logic once, deploy it everywhere. Yet many teams who start a KMP project with enthusiasm find themselves, months later, tangled in a web of expect/actual declarations, convoluted platform abstractions, and a shared layer that has become a bottleneck rather than a time-saver. This section explores the real stakes of shared-layer design, grounded in patterns observed across multiple production projects.

The core challenge is not about learning Kotlin syntax—it's about architectural discipline. When shared code is treated merely as a dumping ground for utility functions, it inevitably fragments. One team I collaborated with initially placed all networking, caching, and business logic into a single shared module. Within three months, the module had grown to over 50 files with circular dependencies, and every platform change required rebuilding the entire shared layer. The promise of "write once, run anywhere" had turned into "write once, debug everywhere."

Why Shared Layers Fail: The Expect/Actual Trap

The expect/actual mechanism is KMP's most powerful yet dangerous feature. It allows you to declare platform-expected APIs and provide actual implementations per target. In theory, it's elegant. In practice, overusing it creates a fragile web of platform dependencies that are hard to test and harder to evolve. For example, a team might create expect/actual for file I/O, date formatting, and logging—three concerns that could be handled by a well-designed abstraction layer without platform-specific hooks. The result: every new platform target requires dozens of actual implementations, and the shared layer becomes a thin wrapper over platform code, defeating its purpose.

A more sustainable approach is to invert the dependency: define interfaces in shared code that describe what you need from the platform, then inject platform implementations through a dependency injection framework. This keeps the shared layer decoupled and testable. For instance, instead of expect/actual for `FileSystem`, define a `FileRepository` interface in common code with `save` and `load` methods. The platform module then provides its implementation using `java.io.File` on Android and `NSFileManager` on iOS. This pattern reduces the number of expect/actual declarations to a minimum—often just for primitive operations like UUID generation or current time.

Another common pitfall is the "shared everything" mentality. Teams sometimes try to share UI logic, navigation, or even view models across platforms. While Compose Multiplatform makes this possible, it often leads to a lowest-common-denominator user experience. The elegance of shared layers lies in knowing what not to share: state management that is inherently platform-specific (e.g., Android's lifecycle-aware ViewModels vs. iOS's Combine publishers), UI rendering, and platform-native navigation. A well-designed shared layer owns pure business logic—validation, data transformation, network calls, caching strategies—and exposes simple interfaces for the platform to consume.

To avoid shared-layer bloat, teams should adopt a layered architecture from day one. The shared module should be divided into submodules: `domain` (entities, use cases), `data` (repositories, data sources), and `network` (API clients, DTOs). Each submodule has a clear responsibility and can be tested independently. This structure also enables incremental adoption: you can start by sharing only the domain layer, then extend to data and network as confidence grows. In the next section, we will examine three concrete architectural patterns that embody this philosophy, comparing their trade-offs in real-world scenarios.

The key takeaway is that shared-layer elegance comes from discipline, not from leveraging every KMP feature. Teams that succeed treat the shared module as a carefully curated library, not a catch-all. They invest time in defining clear boundaries, minimizing platform hooks, and enforcing separation of concerns through code reviews and architecture decision records. This upfront investment pays off when the codebase grows, new platforms are added, or team members change.

Three Architectural Patterns for Shared Layers

Choosing the right architectural pattern for your KMP shared layer is a decision that ripples through every subsequent development phase. This section examines three prevalent patterns—Clean Architecture, Redux-like Unidirectional Flow, and a Lightweight Use-Case Layer—comparing them across criteria like testability, team onboarding, build time, and debugging ease. Each pattern has its proponents and its pitfalls; the goal here is to equip you with a decision framework rather than prescribe a single "best" approach.

Pattern 1: Clean Architecture with Repository Pattern

Clean Architecture, popularized by Robert C. Martin, organizes code into concentric layers: entities, use cases, interface adapters, and frameworks. In KMP, this translates to modules like `domain` (pure Kotlin, no platform dependencies), `data` (implements repositories using Ktor or other multiplatform libraries), and `presentation` (platform-specific ViewModels or state holders). The domain layer defines repository interfaces, and the data layer provides implementations. This pattern excels in testability—domain logic can be unit-tested without any platform mocking—and in maintainability when business rules are complex. However, it introduces boilerplate: each feature may require an interface, an implementation, a use case, and a mapper. For small teams, this overhead can slow initial velocity. A financial services app I'm familiar with adopted Clean Architecture for its KMP layer and found that while the first feature took twice as long to build, subsequent features were integrated in half the time due to clear boundaries and reusable components.

Pattern 2: Redux-Like Unidirectional Flow

Inspired by the Redux pattern from web development, this approach centralizes state in a single store and dispatches actions through reducers. In KMP, it can be implemented with kotlinx.coroutines.flow for reactive state updates. The shared layer contains the store, reducers, and middleware (for side effects like API calls). Platform code subscribes to state changes and dispatches actions. This pattern shines in debugging—every state change is logged, and time-travel debugging becomes possible. It also simplifies concurrency: all state mutations happen on a single coroutine context. The downsides include a steep learning curve for developers unfamiliar with functional patterns, and potential performance issues if the state tree grows large (e.g., frequent recomposition of UI on every state change). A team building a real-time collaboration tool chose this pattern and successfully reduced synchronization bugs by 60%, but reported that onboarding new iOS engineers took two weeks longer than expected.

Pattern 3: Lightweight Use-Case Layer

This pragmatic pattern sits between the previous two. Instead of enforcing a strict layered architecture or a centralized store, it organizes shared code around use cases—simple classes that orchestrate a single business operation. Each use case takes inputs, performs logic (often calling repositories), and returns a result. There is no global state; use cases are stateless and composable. This pattern is easy to learn (resembles service classes in traditional MVC) and has low boilerplate. It works well for apps with moderate complexity where the shared layer primarily handles data transformation and validation. The trade-off is that as the app grows, use cases can become bloated with multiple responsibilities if not refactored. A team building an e-commerce app started with this pattern and shipped the first version in three months, but after adding 20+ features, they had to refactor several use cases into smaller ones to maintain clarity.

Comparison Table

There is no universal winner. The best pattern depends on your team's experience, app complexity, and willingness to invest in upfront structure. In the next section, we will walk through a step-by-step process for migrating a feature from platform-specific code to a shared layer, using the lightweight use-case pattern as a starting point and adding layers as needed.

A Step-by-Step Workflow for Sharing a Feature

Moving a feature from platform-specific implementation to a shared KMP layer is a delicate operation. Rushing it can break existing functionality or create confusing dependencies. This section provides a repeatable workflow—tested across multiple projects—that minimizes risk and maximizes learning. The process assumes you have a working KMP project with at least Android and iOS targets, and you have chosen an architectural pattern (we'll use the lightweight use-case pattern for this walkthrough).

Step 1: Audit the Feature's Dependencies

Before writing any shared code, map out every external dependency the feature uses: network calls, file I/O, device sensors, platform UI, etc. Categorize each dependency as "shareable" (pure Kotlin or multiplatform library available), "abstractable" (can be defined as an interface in shared code with platform implementation), or "platform-locked" (must remain in platform code, e.g., camera hardware). For a typical feature like user profile display, networking (Ktor) and JSON parsing (kotlinx.serialization) are shareable; local caching (SQLDelight) is abstractable; image loading (Coil on Android, SDWebImage on iOS) is platform-locked. This audit produces a dependency map that guides the extraction order.

Step 2: Define Interfaces for Abstractable Dependencies

For each abstractable dependency, create an interface in the shared module. For example, a `UserCache` interface with methods like `saveUserProfile` and `getUserProfile`. Keep these interfaces minimal—the interface segregation principle applies here: a cache interface should not include logging or analytics. Then, implement these interfaces on each platform. On Android, the implementation might use Room; on iOS, CoreData or a simple file store. The key is that the shared layer never knows about Room or CoreData; it only sees the interface. This step often reveals that some dependencies are not as abstractable as first thought—for instance, if the platform's cache has unique threading requirements, you may need to adjust the interface to expose suspend functions or Flow.

Step 3: Extract Business Logic into Use Cases

With interfaces in place, extract the feature's business logic into one or more use case classes. A use case for "load user profile" might: call a repository to fetch the profile from network or cache, validate the result, transform it into a domain model, and return it. Write the use case as a plain Kotlin class with constructor-injected dependencies (repositories, caches). Use kotlinx.coroutines for asynchronous operations. At this stage, do not worry about platform-specific UI or state management—the use case returns a result (e.g., `Result`). Test the use case in commonTest using fake implementations of its dependencies. This is the moment when you catch logic errors that would otherwise surface as platform-specific bugs later.

Step 4: Replace Platform Calls with Shared Use Case Invocations

Now, modify the platform code to call the shared use case instead of its own logic. On Android, a ViewModel might collect the use case's Flow; on iOS, a ViewController might call the use case via a Swift bridge. This step often requires creating a thin adapter that converts between shared domain models and platform-specific UI models. Resist the temptation to put UI-related transformations in the shared layer—keep them in the platform adapter. For example, date formatting for display should happen in platform code, not in the use case. After the replacement, run the feature on each platform to verify it works identically. Expect to find edge cases: maybe the iOS networking library handles cookies differently, or the Android cache has a different eviction policy. These discrepancies are feedback that your interfaces are not yet complete—iterate on them.

Step 5: Iterate and Expand

Once the feature is shared and stable, repeat the process for other features. Each iteration will refine your interfaces and architectural choices. Over time, you will develop a library of reusable use cases and repository implementations that accelerate development of new features. The workflow is not linear; you may discover that a previously abstractable dependency is actually platform-locked due to performance constraints, forcing you to revert and redesign. This is normal. The elegance of shared layers emerges not from a perfect initial design, but from disciplined iteration. In the next section, we will discuss the tools and economics that support this workflow, including build systems and testing infrastructure.

Tools, Stack, and Maintenance Realities

The success of a KMP shared layer depends as much on the supporting toolchain as on the architecture. This section reviews the essential tools—from build systems to testing frameworks—and discusses the economic realities of maintaining a multiplatform codebase. We focus on pragmatic advice rather than exhaustive feature lists, drawing on experiences from teams that have navigated the trade-offs.

Build System: Gradle with Version Catalogs

Gradle is the primary build system for KMP, and its performance is a common pain point. As the shared module grows, Gradle configuration becomes more complex, especially when managing multiple source sets (commonMain, androidMain, iosMain, etc.). Using Gradle version catalogs (`libs.versions.toml`) helps centralize dependency versions and reduces merge conflicts. However, even with catalogs, incremental builds can be slow due to Kotlin/Native compilation. Teams should invest in build caching (Gradle Build Cache, possibly remote) and consider modularizing the shared layer into smaller submodules to parallelize compilation. One team reduced their full build time from 12 minutes to 4 minutes by splitting a monolithic shared module into three submodules: `domain`, `data`, and `network`. The trade-off is increased complexity in dependency management—each submodule must declare its dependencies explicitly.

Serialization: kotlinx.serialization vs. Manual Mapping

Data serialization is a critical decision in KMP. kotlinx.serialization is the standard multiplatform library, supporting JSON, CBOR, and other formats. It generates efficient serializers at compile time and integrates well with Ktor. However, it requires data classes to be annotated with `@Serializable`, which can be invasive if you want to keep domain models clean. Some teams prefer manual mapping using extension functions or mappers, which gives full control but introduces boilerplate. A practical compromise is to use kotlinx.serialization for DTOs (network responses) and manual mapping for domain models. This way, the serialization logic is isolated in the data layer, and domain models remain pure Kotlin objects. For example, a `UserResponse` DTO is annotated with `@Serializable`, and a mapper function converts it to a `User` domain object. This approach adds a mapping step but improves maintainability when the API changes.

Testing Infrastructure: CommonTest and Platform-Specific Tests

KMP provides `commonTest` for tests that run on all targets, and platform-specific test source sets for tests that need platform APIs. A common mistake is to put all tests in `commonTest` even when they require platform mocks. Instead, follow this guideline: place pure logic tests (use cases, domain models) in `commonTest`; place integration tests (repository with real Ktor client) in platform-specific test sets, but consider using a single Android emulator for both Android and iOS via Kotlin/Native test runners if feasible. For mocking, libraries like MockK and kotlinx-coroutines-test are available in common code. For UI testing, the shared layer is not involved—platform-specific UI tests (Espresso, XCTest) remain separate. Investing in commonTest pays off quickly: a single bug caught in commonTest saves the time of debugging on two platforms.

Economic Realities: Developer Productivity vs. Maintenance Burden

Adopting KMP is not free. The initial learning curve, configuration overhead, and debugging of Kotlin/Native issues can reduce developer productivity by 20-30% for the first quarter. However, over a two-year horizon, teams often report a net positive ROI due to reduced duplication. The maintenance burden shifts from "fixing the same bug on two platforms" to "maintaining shared code and platform bridges." The latter is generally lower, but it requires discipline: shared code must be well-tested, documented, and resistant to "creeping features" that bloat the layer. Teams should budget for regular refactoring sessions—every three to four sprints—to prune dead code and simplify interfaces. Ignoring this maintenance leads to the shared-layer decay described in the first section. In the next section, we will explore growth mechanics: how to scale the shared layer as the team and codebase expand.

Scaling the Shared Layer: Growth Mechanics and Team Dynamics

As a KMP project matures, the shared layer grows not only in lines of code but in the number of contributors and the diversity of features. Without deliberate scaling strategies, the shared layer can become a bottleneck where every change requires cross-platform coordination. This section outlines practices for maintaining velocity and code quality as the team expands, based on patterns observed in mid-to-large KMP projects.

Modularization by Feature or by Layer

Two common modularization strategies are by feature (each feature has its own shared module) and by layer (domain, data, network as separate modules). The feature-based approach allows independent versioning and testing of each feature, but can lead to duplicated infrastructure (e.g., each feature may define its own network client). The layer-based approach centralizes infrastructure but can create coupling between features through shared data models. A hybrid strategy works well: organize by layer for core infrastructure (networking, caching, analytics) and by feature for business logic. For example, a `core:network` module handles HTTP client configuration, while `feature:profile` contains profile-specific use cases and repositories. This balance allows teams to work on different features without stepping on each other's toes, while maintaining consistent infrastructure.

Code Ownership and Review Practices

In a growing team, clear code ownership is crucial. Assign each shared module a designated owner or small team responsible for its quality and evolution. For cross-module changes (e.g., modifying a repository interface used by multiple features), require a review from all affected module owners. This may slow down changes initially, but it prevents the "broken windows" effect where small inconsistencies accumulate into technical debt. Use architecture decision records (ADRs) to document why certain patterns were chosen (e.g., "We chose kotlinx.serialization over manual mapping because of compile-time safety"). ADRs help new team members understand the rationale without repeating past debates. In one team, ADRs reduced onboarding time for a new senior engineer from four weeks to two weeks.

Managing Cross-Platform Differences

Even with a well-designed shared layer, platform differences will surface. For example, Android's networking stack handles redirects differently than iOS's, or the iOS keychain behaves differently from Android's EncryptedSharedPreferences. Rather than trying to abstract away every difference, embrace a "controlled divergence" strategy: define a common interface that works for 80% of use cases, and provide platform-specific overrides for the remaining 20%. Document these overrides clearly in the interface's KDoc. For instance, a `SecureStorage` interface might have a `store(key, value)` method, with Android and iOS implementations that handle their respective encryption nuances. When a new platform difference arises, evaluate whether to extend the interface or add a platform-specific extension function. The goal is to keep the shared layer clean while acknowledging that perfect abstraction is rarely achievable.

Continuous Integration and Delivery

As the shared layer grows, CI/CD becomes more critical. Set up a pipeline that compiles and tests the shared module for all targets on every pull request. Use matrix builds to run commonTest on both JVM and native targets (e.g., iOS simulator). This catches platform-specific compilation errors early. For Android, use Gradle Managed Devices or Firebase Test Lab for integration tests. For iOS, leverage Xcode Cloud or GitHub Actions with macOS runners. The pipeline should also run static analysis (detekt, ktlint) on the shared module to enforce coding standards. A well-maintained CI pipeline reduces the fear of breaking other platforms and encourages frequent, small commits. In the next section, we will discuss common pitfalls and how to avoid them, drawing on real-world mistakes.

Risks, Pitfalls, and Mitigations

Even experienced KMP teams encounter pitfalls that can undermine the benefits of shared code. This section catalogs the most common risks—from architectural missteps to tooling limitations—and provides actionable mitigations. The goal is not to discourage adoption but to prepare you for the challenges that lie ahead.

Pitfall 1: Over-Abstraction and Premature Optimization

Eager to maximize code sharing, some teams abstract every platform detail from day one. They create interfaces for logging, file I/O, threading, even UI rendering. The result is a shared layer that is so generic it requires platform-specific implementations for almost every operation, negating the sharing benefit. Mitigation: Start by sharing only pure business logic and data transformations. Add abstractions only when you encounter a platform difference that genuinely requires them. A good rule of thumb is the "three strikes" rule: if you find yourself writing the same platform-specific code in three places, then consider creating an abstraction. This keeps the shared layer focused and maintainable.

Pitfall 2: Ignoring Kotlin/Native Performance Characteristics

Kotlin/Native compiles to native binaries via LLVM, which can introduce performance quirks. For example, using `kotlinx.coroutines` on iOS can lead to stack overflow if coroutines are deeply nested, due to how Kotlin/Native handles continuations. Another issue is that reflection is limited on native (no `KClass` introspection at runtime). Mitigation: Profile early and often. Use the `kotlinx.coroutines` debug mode to detect excessive allocations. Avoid heavy use of reflection in common code; prefer sealed classes and when expressions for polymorphic behavior. If performance issues arise, consider moving performance-critical code to platform-specific implementations using expect/actual, but only after profiling confirms the bottleneck.

Pitfall 3: Neglecting the iOS Build Experience

Android developers often lead KMP projects, and the iOS build experience can suffer as a result. Kotlin/Native compilation is slower than Kotlin/JVM, and Xcode integration via the Kotlin Gradle plugin can be finicky. Common issues include mismatched CocoaPods versions, missing simulator architectures, and long build times. Mitigation: Invest in the iOS developer experience. Set up a CI pipeline that builds the iOS framework on every commit. Provide clear documentation for iOS developers on how to set up Xcode and CocoaPods. Consider using Swift Package Manager instead of CocoaPods for simpler integration. One team assigned a dedicated iOS engineer to maintain the KMP integration, which reduced iOS build failures by 70%.

Pitfall 4: Shared State and Concurrency Bugs

Shared mutable state across platforms is a recipe for subtle bugs. For example, if a shared singleton holds a cache, and both Android and iOS access it from different threads, you may encounter race conditions that are hard to reproduce. Mitigation: Prefer stateless use cases and repository interfaces that return results (or Flows) rather than mutating shared state. If you must use shared state, protect it with a `Mutex` from kotlinx.coroutines. Use `StateFlow` for observable state instead of mutable properties. Test concurrency scenarios in commonTest using `runTest` with `TestCoroutineScheduler`. By designing for immutability from the start, you avoid a class of bugs that are notoriously difficult to debug across platforms.

Pitfall 5: Documentation Decay

As the shared layer evolves, documentation (both inline and external) often falls out of sync. Developers may not know which interfaces are stable and which are experimental, leading to breaking changes or duplicated work. Mitigation: Treat shared module APIs as public libraries. Use Kotlin's `@RequiresOptIn` annotation to mark experimental APIs. Maintain a changelog for the shared module. Enforce that every public interface has KDoc comments. In code reviews, require that API changes are accompanied by updates to the documentation. This discipline pays off when onboarding new team members or when external contributors join.

Mini-FAQ: Common Questions and Decision Checklist

This section addresses the most frequent questions that arise when teams design and maintain KMP shared layers. It also includes a decision checklist to help you evaluate whether a given piece of logic belongs in shared code or should remain platform-specific. The answers are based on collective experience rather than absolute rules—each situation has nuances.

FAQ 1: When should I use expect/actual instead of dependency injection?

Use expect/actual for low-level platform primitives that are accessed frequently and have very simple interfaces, such as `UUID.randomUUID()`, `currentTimeMillis()`, or `Platform.name`. For anything more complex—like file storage, networking, or database access—prefer dependency injection with interfaces defined in common code. The reason is testability: interfaces can be mocked in commonTest, while expect/actual declarations cannot be easily replaced without platform-specific test doubles. As a rule of thumb: if the implementation is more than five lines of code, use an interface.

FAQ 2: How do I handle platform-specific UI state in shared code?

Generally, do not. UI state that reflects platform-specific lifecycle (e.g., Android's onSaveInstanceState) or user interaction patterns (e.g., iOS swipe gestures) should remain in platform code. However, pure business state (e.g., user authentication status, shopping cart contents) can be managed in shared code using `StateFlow` or a simple state holder. The shared layer exposes a `StateFlow`, and each platform observes it and renders accordingly. The key is that the shared state does not reference any platform UI classes—it only holds data.

FAQ 3: What about sharing navigation logic?

Navigation is notoriously platform-specific. Android uses Jetpack Navigation or Compose Navigation; iOS uses Storyboards, SwiftUI NavigationStack, or coordinator patterns. Sharing navigation routes or deep link handling is possible via a shared enum of routes, but the actual navigation execution must be platform-specific. Define a `Navigator` interface in common code with methods like `navigateTo(route: Route)`, and implement it on each platform. This keeps the shared layer aware of navigation possibilities without dictating the implementation.

FAQ 4: How do I debug issues that only occur on one platform?

First, isolate whether the issue is in shared code or platform code. Write a commonTest that exercises the shared logic with the same inputs that trigger the issue. If the test passes, the bug is likely in the platform implementation or bridge. If the test fails, fix the shared logic. For platform-specific issues, use platform-native debugging tools (Android Studio debugger, Xcode Instruments). For Kotlin/Native issues, enable Kotlin/Native memory manager logging by setting the `kotlin.native.memory.logLevel` Gradle property. Additionally, consider using the `kotlinx.coroutines` debug mode to track coroutine execution on iOS.

Decision Checklist: To Share or Not to Share?

• Is the logic pure business logic (no UI, no platform APIs)? Yes → Share. No → Consider platform-specific.
• Does the logic need to be identical across platforms for consistency? Yes → Share. No → Evaluate trade-offs.
• Is a mature multiplatform library available? Yes → Share. No → Consider abstracting the dependency.
• Is the logic performance-critical with platform-specific optimizations? Yes → Keep platform-specific. No → Share.
• Is the logic likely to change frequently due to platform updates? Yes → Consider platform-specific to avoid churn. No → Share.

Use this checklist as a starting point, but always consider the context. The goal is not to maximize sharing percentage, but to maximize developer productivity and code quality. Sometimes, leaving a piece of logic platform-specific is the more elegant choice.

Synthesis and Next Actions

Throughout this guide, we have explored the art and science of designing shared layers in Kotlin Multiplatform. The central theme is that elegance comes from restraint and intentional design, not from using every feature of KMP. As you close this article, the question is: what should you do next? This section synthesizes the key takeaways and provides a concrete action plan for applying these patterns in your own projects.

Key Takeaways

First, shared layers succeed when they are built on clear architectural boundaries. Whether you choose Clean Architecture, Redux-like flows, or lightweight use cases, the critical factor is that each module has a single responsibility and minimal dependencies on platform code. Second, avoid the expect/actual trap by preferring dependency injection for complex platform interactions. Third, invest in commonTest—it is the most efficient way to catch bugs before they multiply across platforms. Fourth, scale your shared layer through modularization and clear ownership, not by monolithic growth. Fifth, acknowledge that not everything should be shared; platform-specific code is not a failure, but a pragmatic choice.

Action Plan for Your Next Sprint

1. Audit your current codebase: Identify one feature that is currently implemented separately on Android and iOS. Map its dependencies using the audit process from Section 3.
2. Design interfaces: For each abstractable dependency, define a minimal interface in a new shared module. Implement the interface on each platform.
3. Extract a use case: Move the feature's business logic into a use case class in the shared module. Write commonTest for it.
4. Replace platform calls: Modify the platform code to use the shared use case. Run the feature on both platforms and fix any discrepancies.
5. Document and review: Write KDoc for the new interfaces and use cases. Have a colleague review the changes, focusing on the abstraction boundaries.
6. Iterate: Repeat the process for another feature. After three features, review your shared module structure and refactor if needed.

Final Reflection

The elegance of shared layers is not about writing less code—it is about writing the right code once, in a way that is maintainable, testable, and adaptable. KMP is a powerful tool, but like any tool, its value depends on the skill of the craftsman. By applying the patterns and disciplines discussed here, you can build shared layers that are not just a technical achievement but a genuine force multiplier for your team. As you embark on this journey, remember that the goal is not perfection, but progress. Each feature you share brings you one step closer to the vision of seamless multiplatform development.