Imagine you're opening a chain of coffee shops. To keep the brand consistent, you create a "Master Recipe Book." Every single shop, regardless of whether it's in New York, Tokyo, or London, uses the same recipe for a latte. That's your core business logic. However, the way those shops actually operate varies. The New York shop uses a specific US-based electricity provider, the Tokyo shop follows Japanese health codes, and the London shop handles VAT taxes. You can't have one single "global" way to pay the electric bill, but you absolutely can have one single way to make a latte.

Kotlin Multiplatform (KMP) project structure works exactly like this. Your commonMain is the Master Recipe Book. Your androidMain and iosMain are the local shop operations. You put everything that can be shared in the center, and you carve out specific spaces for the things that must be platform-specific.

The Blueprint of a Shared Module

When you first open a KMP project, the folder hierarchy can look a bit overwhelming. I've seen a lot of developers try to fight this structure by forcing everything into one folder, but that's a recipe for build errors. Instead, look at it as a concentric circle. At the heart is commonMain. This is where the bulk of your code lives—your data models, your business logic, and your API definitions.

Let's say we're building a Currency Converter. The logic to calculate amount * exchangeRate is the same whether the user is on an iPhone or a Pixel. That code goes in commonMain. But the way you save that exchange rate to a local database? Android uses SQLite/Room, and iOS might use CoreData or a different SQLite wrapper. That's why we have the platform-specific source sets.

Mapping the Source Sets

You'll notice the structure usually follows a pattern like src/commonMain/kotlin, src/androidMain/kotlin, and src/iosMain/kotlin. Here is how I mentally map these when I'm architecting a feature:

• commonMain: The "What." (e.g., "I need to fetch the latest USD to EUR rate and save it.")
• androidMain: The "How" for Android. (e.g., "Use SharedPreferences to cache this rate.")
• iosMain: The "How" for iOS. (e.g., "Use NSUserDefaults to cache this rate.")

The Glue: Configuring the Gradle Build

The magic that tells Kotlin "this code belongs to iOS and this code belongs to Android" happens in your build.gradle.kts. You aren't just declaring dependencies; you're defining targets. I always recommend being explicit here. If you don't tell Gradle that you're targeting iosArm64 or iosSimulatorArm64, your IDE will just show you red squiggly lines in your iOS folders.

kotlin {
    androidTarget() 
    
    // We define the iOS targets specifically
    iosArm64() 
    iosSimulatorArm64() 

    sourceSets {
        val commonMain by getting {
            dependencies {
                // Put your multiplatform libraries here (e.g., Ktor, kotlinx.serialization)
                implementation("io.ktor:ktor-client-core:2.3.0")
            }
        }
        val androidMain by getting {
            dependencies {
                // Android-specific libraries (e.g., Android-specific Ktor engine)
                implementation("io.ktor:ktor-client-okhttp:2.3.0")
            }
        }
        val iosMain by creating {
            dependsOn(commonMain)
            dependencies {
                // iOS-specific libraries (e.g., Darwin engine)
                implementation("io.ktor:ktor-client-darwin:2.3.0")
            }
        }
    }
}

One thing to watch out for: notice the dependsOn(commonMain). This is the umbilical cord. It ensures that your platform-specific code has access to all the models and logic you wrote in the shared core. Without this link, your iosMain folder is just a lonely island with no idea what the rest of the app is doing.

📋 Practical Task

Project Structure: Architecting a Local-Storage Currency Cache

You are tasked with setting up the folder and configuration structure for a new KMP module called :shared-finance. This module will handle currency conversion logic and platform-specific caching.

Requirements:

• Create a build.gradle.kts configuration that targets Android, iOS Arm64, and iOS Simulator Arm64.
• Define a source set structure where commonMain contains the ktor-client-core dependency.
• Ensure androidMain uses the okhttp engine and iosMain uses the darwin engine.
• Map out the directory path where you would place a Kotlin file that handles the shared logic for calculating currency exchange (e.g., ExchangeCalculator.kt).
• Map out the directory path where you would place the Android-specific implementation of the cache (e.g., AndroidCacheStorage.kt).