When you first dive into Kotlin Multiplatform (KMP), it's easy to get tunnel vision. You see the expect and actual keywords and think, "Perfect, whenever I hit a platform wall, I'll just punch a hole through it with these." I'll be honest: that's how most of us start. But if you build your entire architecture around expect and actual, you aren't really building a shared architecture—you're just building a fragmented library that happens to live in one folder.

The Expect/Actual Trap

Let's say we're building a Currency Converter. You need to fetch exchange rates from an API and save the user's preferred currency to the device's local storage. The naive approach is to create an expect function for the storage part:

// Shared Module
expect fun savePreferredCurrency(code: String)
expect fun getPreferredCurrency(): String?

Then you go to your Android source set and implement it using SharedPreferences, and you go to your iOS source set and implement it using NSUserDefaults. On the surface, this works. The code compiles, the app runs, and you've "shared" the logic. But here is where it breaks: your shared business logic is now tightly coupled to these global functions. Testing becomes a nightmare because you can't easily mock a global expect function in a unit test without jumping through hoops. You've essentially created a set of global variables that vary by platform, which is exactly what we try to avoid in modern software engineering.

The Interface-Driven Core

The better way—the way that actually scales—is to treat your shared module as a "pure" core that defines what needs to happen, while the platform modules decide how it happens. Instead of using expect for the storage logic, we use a standard Kotlin interface. I call this the "Plug-in" approach.

// Shared Module
interface SettingsStorage {
    fun saveCurrency(code: String)
    fun getCurrency(): String?
}

class CurrencyManager(private val storage: SettingsStorage) {
    fun updateCurrency(newCode: String) {
        // Business logic: validate code, then save
        if (newCode.length == 3) {
            storage.saveCurrency(newCode)
        }
    }
}

Now, the CurrencyManager doesn't care if it's running on a toaster or an iPhone. It just knows it has something that satisfies the SettingsStorage contract. You implement the interface in the Android and iOS modules and "inject" the implementation when you initialize the app. This shifts the architectural burden from the compiler (which is what expect/actual uses) to the dependency graph. It sounds like more work up front, but it means your core logic is 100% platform-independent and 100% testable using a simple mock implementation of the interface.

Where the Friction Actually Lives

You might be wondering: "If interfaces are so great, why does expect/actual even exist?" It's because there are things you simply cannot abstract with an interface—things like platform-specific types or low-level system APIs that need to be called during object construction. For example, if you need to provide a Context on Android to initialize a library, an interface won't save you from the fact that the Android app must pass that Context in from the Activity.

The trade-off is a matter of granularity. Use expect/actual for the "plumbing"—the tiny, low-level utility functions that provide a platform-specific value or type. Use interfaces for "capabilities"—the actual business behaviors of your app. If you find yourself writing expect for anything that contains business logic or data orchestration, you've gone too far. You're no longer sharing a platform-agnostic core; you're just writing two different apps in the same file.

📋 Practical Task

Refactoring the Network Logger

You've inherited a KMP project where the previous developer used the "naive" approach for logging network requests. Currently, there is an expect fun logRequest(url: String) defined in the shared module, with actual implementations using Log.d on Android and print() on iOS.

This is making unit tests noisy and making it impossible to swap the logger for a crash-reporting tool (like Firebase Crashlytics) in the future without changing the shared core.

Your Task:

• Remove the expect fun logRequest and its actual implementations.
• Create a NetworkLogger interface in the shared module.
• Refactor the ApiService class in the shared module to accept this interface via its constructor.
• Write a mock implementation of the NetworkLogger in the shared test source set that saves logs to a list instead of printing them, proving that you can now test the ApiService without triggering platform-specific logging.