Kotlin Multiplatform

Kotlin Multiplatform: Platform Abstraction Decisions

Expert guidance for KMP architecture in Amethyst - deciding what to share vs keep platform-specific.

When to Use This Skill

Making platform abstraction decisions:

• "Should I create expect/actual or keep Android-only?"
• "Can I share this ViewModel logic?"
• "Where does this crypto/JSON/network implementation belong?"
• "This uses Android Context - can it be abstracted?"
• "Is this code in the wrong module?"
• Preparing for iOS/web/wasm targets
• Detecting incorrect placements

Abstraction Decision Tree

Central question: "Should this code be reused across platforms?"

Follow this decision path (< 1 minute):

Q: Is it used by 2+ platforms?
├─ NO  → Keep platform-specific
│         Example: Android-only permission handling
│
└─ YES → Continue ↓

Q: Is it pure Kotlin (no platform APIs)?
├─ YES → commonMain
│         Example: Nostr event parsing, business rules
│
└─ NO  → Continue ↓

Q: Does it vary by platform or by JVM vs non-JVM?
├─ By platform (Android ≠ iOS ≠ Desktop)
│  → expect/actual
│  Example: Secp256k1Instance (uses different security APIs)
│
├─ By JVM (Android = Desktop ≠ iOS/web)
│  → jvmAndroid
│  Example: Jackson JSON parsing (JVM library)
│
└─ Complex/UI-related
   → Keep platform-specific
   Example: Navigation (Activity vs Window too different)

Final check:
Q: Maintenance cost of abstraction < duplication cost?
├─ YES → Proceed with abstraction
└─ NO  → Duplicate (simpler)

Real Examples from Codebase

Crypto → expect/actual:

// commonMain - expect declaration
expect object Secp256k1Instance {
    fun signSchnorr(data: ByteArray, privKey: ByteArray): ByteArray
}

// androidMain - uses Android Keystore
// jvmMain - uses Desktop JVM crypto
// iosMain - uses iOS Security framework

Why: Each platform has different security APIs.

JSON parsing → jvmAndroid:

// quartz/build.gradle.kts
val jvmAndroid = create("jvmAndroid") {
    api(libs.jackson.module.kotlin)
}

Why: Jackson is JVM-only, works on Android + Desktop, not iOS/web.

Navigation → platform-specific:

• Android: MainActivity (Activity + Compose Navigation)
• Desktop: Window + sidebar + MenuBar

Why: UI paradigms fundamentally different.

Mental Model: Source Sets as Dependency Graph

Think of source sets as a dependency graph, not folders.

┌─────────────────────────────────────────────┐
│ commonMain = Contract (pure Kotlin)         │
│ - Business logic, protocol, data models     │
│ - No platform APIs                          │
└────────────┬────────────────────────────────┘
             │
             ├──────────────────────┬────────────────────
             │                      │
             ▼                      ▼
   ┌───────────────────┐  ┌──────────────────┐
   │ jvmAndroid        │  │ iosMain          │
   │ JVM libs shared   │  │ iOS common       │
   │ - Jackson         │  │                  │
   │ - OkHttp          │  └────┬─────────────┘
   └───┬───────────┬───┘       │
       │           │           │
       ▼           ▼           ├─→ iosArm64Main
  ┌─────────┐ ┌──────────┐     └─→ iosSimulatorArm64Main
  │android  │ │jvmMain   │
  │Main     │ │(Desktop) │
  └─────────┘ └──────────┘

Future: jsMain, wasmMain

Key insight: jvmAndroid is NOT a platform - it's a shared JVM layer.

The jvmAndroid Pattern

Unique to Amethyst. Shares JVM libraries between Android + Desktop.

When to Use jvmAndroid

Use jvmAndroid when:

• ✅ JVM-specific libraries (Jackson, OkHttp, url-detector)
• ✅ Android implementation = Desktop implementation (same JVM)
• ✅ Library doesn't work on iOS/web

Do NOT use jvmAndroid for:

• ❌ Pure Kotlin code (use commonMain)
• ❌ Platform-specific APIs (use androidMain/jvmMain)
• ❌ Code that should work on all platforms

Example from quartz/build.gradle.kts

// Must be defined BEFORE androidMain and jvmMain
val jvmAndroid = create("jvmAndroid") {
    dependsOn(commonMain.get())

    dependencies {
        api(libs.jackson.module.kotlin)  // JSON parsing - JVM only
        api(libs.url.detector)            // URL extraction - JVM only
        implementation(libs.okhttp)       // HTTP client - JVM only
    }
}

// Both depend on jvmAndroid
jvmMain { dependsOn(jvmAndroid) }
androidMain { dependsOn(jvmAndroid) }

Why Jackson in jvmAndroid, not commonMain?

• Jackson is JVM-specific library
• Works on Android (runs on JVM)
• Works on Desktop (runs on JVM)
• Does NOT work on iOS (not JVM) or web (not JVM)

Web/wasm consideration: For future web support, consider migrating from Jackson → kotlinx.serialization (see Target-Specific Guidance).

What to Abstract vs Keep Platform-Specific

Quick decision guidelines based on codebase patterns:

Always Abstract

• Crypto (Secp256k1, encryption, signing)
• Core protocol logic (Nostr events, NIPs)
• Why: Needed everywhere, platform security APIs vary

Often Abstract

• I/O operations (file reading, caching)
• Logging (platform logging systems differ)
• Serialization (if using kotlinx.serialization)
• Why: Commonly reused, platform implementations available

Sometimes Abstract

• Business logic: YES - state machines, data processing
• ViewModels: YES - state + business logic shareable (StateFlow/SharedFlow)
• Screen layouts: NO - platform-native (Window vs Activity)
• Why: ViewModels contain platform-agnostic state; Screens render differently per platform

Rarely Abstract

• Complex UI components (composables with heavy platform dependencies)
• Why: Platform paradigms can differ significantly

Never Abstract

• Navigation (Activity vs Window fundamentally different)
• Permissions (Android vs iOS APIs incompatible)
• Platform UX patterns
• Why: Too platform-specific, abstraction creates leaky APIs

Evidence from shared-ui-analysis.md

expect/actual Mechanics

When to use: Code needed by 2+ platforms, varies by platform.

Pattern Categories from Codebase

Objects (singletons):

// 24 expect declarations found, common pattern:
expect object Secp256k1Instance { ... }
expect object Log { ... }
expect object LibSodiumInstance { ... }

Classes (instantiable):

expect class AESCBC { ... }
expect class DigestInstance { ... }

Functions (utilities):

expect fun platform(): String
expect fun currentTimeSeconds(): Long

See references/expect-actual-catalog.md for complete catalog with rationale.

Target-Specific Guidance

Android, JVM (Desktop), iOS - Current Primary Targets

Status: Mature patterns, stable APIs

Android (androidMain):

• Uses Android framework (Activity, Context, etc.)
• secp256k1-kmp-jni-android (0.23.0 in libs.versions.toml) for crypto
• AndroidX libraries

Desktop JVM (jvmMain):

• Uses Compose Desktop (Window, MenuBar, etc.)
• secp256k1-kmp-jni-jvm (same 0.23.0 line) for crypto
• Pure JVM libraries

iOS (iosMain):

• Mature target — actively built and tested
• Architecture targets: iosArm64, iosSimulatorArm64, iosX64 (plus macosArm64 for host tooling)
• Platform APIs via platform.posix, Security framework

Web, wasm - Future Targets

Status: Not yet implemented, consider for future-proofing

Constraints to know:

• ❌ No platform.posix (file I/O different)
• ❌ No JVM libraries (Jackson, OkHttp won't work)
• ❌ Different async model (JS event loop vs threads)

Future-proofing tips: 1. Prefer pure Kotlin in commonMain 2. Use kotlinx.* libraries:

• kotlinx.serialization instead of Jackson
• ktor instead of OkHttp (ktor supports web)
• kotlinx.datetime instead of custom date handling

3. Avoid platform.posix for file operations 4. Test abstractions work without JVM assumptions

Example migration path:

// Current: jvmAndroid (JVM-only)
api(libs.jackson.module.kotlin)

// Future: commonMain (all platforms)
api(libs.kotlinx.serialization.json)

Integration: When to Invoke Other Skills

Invoke gradle-expert

Trigger gradle-expert skill when encountering:

• Dependency conflicts (e.g., secp256k1-android vs secp256k1-jvm version mismatch)
• Build errors related to source sets
• Version catalog issues (libs.versions.toml)
• "Duplicate class" errors
• Performance/build time issues

Example trigger:

Error: Duplicate class found: fr.acinq.secp256k1.Secp256k1

→ Invoke gradle-expert for dependency conflict resolution.

Flags to Raise

Platform code in commonMain:

// ❌ INCORRECT - Android API in commonMain
expect fun getContext(): Context  // Context is Android-only!

→ Flag: "Android API in commonMain won't compile on other platforms"

Duplicated business logic:

// ❌ INCORRECT - Same logic in both
// androidMain/.../CryptoUtils.kt
fun validateSignature(...) { ... }

// jvmMain/.../CryptoUtils.kt
fun validateSignature(...) { ... }  // Duplicated!

→ Flag: "Business logic duplicated, should be in commonMain or expect/actual"

Reinventing wheel - suggest KMP alternatives:

• Custom date/time → kotlinx.datetime
• OkHttp → ktor (supports web)
• Jackson → kotlinx.serialization
• Custom UUID → kotlinx.uuid (when stable)

Common Pitfalls

1. Over-Abstraction

Problem: Creating expect/actual for UI components

// ❌ BAD
expect fun NavigationComponent(...)

Why: Navigation paradigms too different (Activity vs Window) Fix: Keep platform-specific, accept duplication

2. Under-Sharing

Problem: Duplicating business logic across platforms

// ❌ BAD - duplicated in androidMain and jvmMain
fun parseNostrEvent(json: String): Event { ... }

Why: Bug fixes need to be applied twice, tests duplicated Fix: Move to commonMain (pure Kotlin) or create expect/actual

3. Leaky Abstractions

Problem: Platform code in commonMain

// commonMain - ❌ BAD
import android.content.Context  // Won't compile on iOS!

Fix: Use expect/actual or dependency injection

4. Premature Abstraction

Problem: Creating expect/actual before second platform needs it

// ❌ BAD - only used on Android currently
expect fun showNotification(...)

Why: Wrong abstraction boundaries, wasted effort Fix: Wait until iOS actually needs it, then abstract

5. Wrong Source Set

Problem: JVM libraries in commonMain

// commonMain - ❌ BAD
import com.fasterxml.jackson.databind.ObjectMapper

Why: Jackson won't compile on iOS/web Fix: Move to jvmAndroid or migrate to kotlinx.serialization

Quick Reference

See Also

• references/abstraction-examples.md - Good/bad abstraction examples with rationale
• references/source-set-hierarchy.md - Visual hierarchy with Amethyst examples
• references/expect-actual-catalog.md - All 24 expect/actual pairs with "why abstracted"
• references/target-compatibility.md - Platform constraints and future-proofing

Scripts

• scripts/validate-kmp-structure.sh - Detect incorrect placements, validate source sets
• scripts/suggest-kmp-dependency.sh - Suggest KMP library alternatives (ktor, kotlinx.serialization, etc.)

Abstraction Examples from Amethyst Codebase

Real examples of abstraction decisions with rationale.

Good Abstractions (Why They Work)

1. Secp256k1Instance - Crypto Signing

Location: expect in commonMain, actual in androidMain/jvmMain/iosMain

Code:

// quartz/src/commonMain/.../Secp256k1Instance.kt
expect object Secp256k1Instance {
    fun signSchnorr(data: ByteArray, privKey: ByteArray): ByteArray
    fun verifySchnorr(signature: ByteArray, hash: ByteArray, pubKey: ByteArray): Boolean
}

Why abstracted:

• Used by all platforms (Android, Desktop, iOS)
• Security APIs fundamentally different:
• Android: secp256k1-kmp-jni-android (Android Keystore integration)
• Desktop: secp256k1-kmp-jni-jvm (pure JVM crypto)
• iOS: Native Security framework
• Core protocol requirement (Nostr signatures)

Decision rationale: Always abstract crypto - varies by platform security APIs, critical for all platforms.

---

2. Log - Platform Logging

Location: expect object in commonMain

Code:

// quartz/src/commonMain/.../Log.kt
expect object Log {
    fun d(tag: String, message: String)
    fun w(tag: String, message: String, throwable: Throwable?)
    fun e(tag: String, message: String, throwable: Throwable?)
}

Why abstracted:

• Used throughout quartz module (protocol library)
• Logging systems differ:
• Android: android.util.Log
• Desktop: println or logging framework
• iOS: NSLog or OSLog
• Simple interface, easy to implement

Decision rationale: Often abstract logging - platform systems differ, widely used, simple interface.

---

3. Platform Utils - Time & Platform Name

Location: expect functions in commonMain

Code:

// quartz/src/commonMain/.../Platform.kt
expect fun platform(): String
expect fun currentTimeSeconds(): Long

Why abstracted:

• Used by Nostr event creation (timestamps)
• Platform name for debugging
• Simple utilities, clear platform boundary

Decision rationale: Platform utilities are good abstraction candidates - simple, useful everywhere.

---

4. Jackson JSON (jvmAndroid Pattern)

Location: jvmAndroid source set

Code:

// quartz/build.gradle.kts
val jvmAndroid = create("jvmAndroid") {
    api(libs.jackson.module.kotlin)  // JVM-only library
}

Why jvmAndroid (not commonMain):

• Jackson is JVM-specific library
• Works on Android (JVM) + Desktop (JVM)
• Does NOT work on iOS (not JVM) or web (not JVM)
• Performance-critical JSON parsing

Decision rationale: Use jvmAndroid for JVM libraries shared between Android and Desktop.

Future consideration: For web support, migrate to kotlinx.serialization (works on all platforms).

---

Bad/Over-Abstractions (Why They Failed)

1. Navigation Abstraction (Avoided)

What COULD have been done:

// ❌ Over-abstraction - DON'T DO THIS
expect interface Navigator {
    fun navigate(route: String)
    fun popBackStack()
}

Why NOT abstracted:

• Navigation paradigms fundamentally different:
• Android: Activity + Compose Navigation + back stack
• Desktop: Window + screen state + no back stack concept
• Complex APIs don't map well
• Creates leaky abstraction

Actual approach: Keep platform-specific

• Android: INav interface + Compose Navigation
• Desktop: Simple screen enum + state

Decision rationale: Never abstract navigation - platforms too different, abstraction would be leaky.

---

2. String Resources (Abstraction Planned)

Current state: Platform-specific (over-duplication)

Problem:

// Android uses R.string.*
Text(stringResource(R.string.post_not_found))

// Desktop uses hardcoded strings
Text("Post not found")

Why NOT yet abstracted: Waiting for second platform to fully implement UI, then will create StringProvider interface.

Planned abstraction:

// commonMain
interface StringProvider {
    fun get(key: String): String
}

// androidMain
class AndroidStringProvider(context: Context): StringProvider { ... }

// jvmMain
class DesktopStringProvider: StringProvider { ... }

Lesson: Don't abstract prematurely - wait until second platform needs it, then create proper abstraction.

---

Platform-Specific Code (Why NOT Abstracted)

1. MainActivity (Android Activity)

Location: amethyst/src/main/.../MainActivity.kt

Code:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        enableEdgeToEdge()
        setContent {
            AmethystTheme {
                AccountScreen(accountStateViewModel)
            }
        }
    }
}

Why platform-specific:

• AppCompatActivity is Android framework
• Activity lifecycle unique to Android
• enableEdgeToEdge() is Android-specific API
• No equivalent on Desktop (uses Window)

Decision rationale: Android Activity is platform-specific by nature.

---

2. Desktop Window & MenuBar

Location: desktopApp/src/jvmMain/.../Main.kt

Code:

fun main() = application {
    Window(
        onCloseRequest = ::exitApplication,
        title = "Amethyst"
    ) {
        MenuBar {
            Menu("File") {
                Item("New Note", onClick = { ... }, shortcut = KeyShortcut(Key.N, ctrl = true))
                Item("Quit", onClick = ::exitApplication)
            }
        }
        NavigationRail { ... }  // Sidebar navigation
    }
}

Why platform-specific:

• Window, MenuBar, NavigationRail are Compose Desktop APIs
• Keyboard shortcuts (Ctrl+N) are desktop paradigm
• Sidebar navigation vs Android bottom nav
• No equivalent on Android

Decision rationale: Desktop UX patterns are platform-specific by nature.

---

3. AccountViewModel (Android ViewModel)

Location: amethyst/.../AccountStateViewModel.kt

Partially abstracted:

• Business logic → IAccountState interface (can be shared)
• UI state + lifecycle → AndroidX ViewModel (Android-only)

Why not fully abstracted:

• AndroidX ViewModel lifecycle tied to Android
• Desktop doesn't need ViewModel (simpler state management)
• SavedStateHandle is Android-specific

Decision rationale: Extract business logic to interface, keep UI state platform-specific.

---

Migration Examples (Android → Shared)

Example 1: PubKeyFormatter (Pure Kotlin)

Before:

// amethyst/ui/note/PubKeyFormatter.kt
fun String.toDisplayHexKey(): String {
    return "${take(8)}:${takeLast(8)}"
}

After:

// commons/commonMain/formatters/PubKeyFormatter.kt
fun String.toDisplayHexKey(): String {
    return "${take(8)}:${takeLast(8)}"
}

// Both apps use it
import com.vitorpamplona.amethyst.commons.formatters.toDisplayHexKey

Why successful:

• Pure Kotlin, no platform dependencies
• Widely reused
• Simple utility function

---

Example 2: TimeAgoFormatter (Requires Abstraction)

Problem:

// Uses Android R.string.*
fun timeAgo(timestamp: Long): String {
    return context.getString(R.string.x_minutes_ago, minutes)
}

Solution: Abstract string resources

// commonMain
fun timeAgo(timestamp: Long, stringProvider: StringProvider): String {
    return stringProvider.get("x_minutes_ago", minutes)
}

// androidMain
stringProvider = AndroidStringProvider(context)

// jvmMain
stringProvider = DesktopStringProvider()

Why successful: Clear platform boundary (string resources), useful on both platforms.

---

Decision Pattern Summary

Complete expect/actual Catalog

All 24 expect declarations in Amethyst quartz module with rationale.

Pattern Analysis

Objects (Singletons) - 19 total

Most common pattern for platform-specific singletons:

• Crypto: Secp256k1Instance, LibSodiumInstance, Sha256
• I/O: UriParser, UrlEncoder, GZip
• Utils: Log, Platform, SecureRandom

Classes (Instantiable) - 4 total

For objects that need to maintain state:

• AESCBC, AESGCM (cipher state)
• DigestInstance, MacInstance (hash/MAC state)
• BigDecimal, BitSet (data structures)

Functions - 2 total

Simple utilities:

• platform(), currentTimeSeconds()

Why Abstracted Categories

Crypto (8 items)

Always abstract: Security APIs fundamentally different across platforms

• Android: Android Keystore, secp256k1-android
• Desktop: JVM crypto, secp256k1-jvm
• iOS: Security framework, native crypto

I/O & Platform Utils (7 items)

Often abstract: File systems, URLs, compression differ

• Platform storage APIs
• URL handling varies
• Compression libraries differ

Data Structures (2 items)

Abstract when missing: Not available in Kotlin common stdlib

• BigDecimal, BitSet not in common

JSON/Parsing (3 items)

Platform-specific optimization: Uses platform JSON libraries

• Android/Desktop: Jackson (via jvmAndroid)
• iOS: Native parsers

Logging (1 item)

Always abstract: Platform logging systems differ

• Android: android.util.Log
• Desktop: println or logging framework
• iOS: NSLog or OSLog

Actual Implementation Examples

Simple Object Pattern

// commonMain
expect object Log {
    fun d(tag: String, message: String)
}

// androidMain
actual object Log {
    actual fun d(tag: String, message: String) {
        android.util.Log.d(tag, message)
    }
}

// jvmMain
actual object Log {
    actual fun d(tag: String, message: String) {
        println("[$tag] $message")
    }
}

Complex Object with Dependencies

// commonMain
expect object Secp256k1Instance {
    fun signSchnorr(data: ByteArray, privKey: ByteArray): ByteArray
}

// androidMain - uses JNI bindings
actual object Secp256k1Instance {
    actual fun signSchnorr(data: ByteArray, privKey: ByteArray): ByteArray {
        return fr.acinq.secp256k1.Secp256k1.signSchnorr(data, privKey, null)
    }
}

// jvmMain - different JNI library
actual object Secp256k1Instance {
    actual fun signSchnorr(data: ByteArray, privKey: ByteArray): ByteArray {
        return fr.acinq.secp256k1.Secp256k1.signSchnorr(data, privKey, null)
    }
}

// iosMain - native iOS implementation
actual object Secp256k1Instance {
    actual fun signSchnorr(data: ByteArray, privKey: ByteArray): ByteArray {
        // Uses iOS Security framework or native lib
    }
}

Class Pattern

// commonMain
expect class BigDecimal {
    constructor(value: String)
    fun add(other: BigDecimal): BigDecimal
    override fun toString(): String
}

// jvmAndroid (works on Android + Desktop)
actual typealias BigDecimal = java.math.BigDecimal

// iosMain
actual class BigDecimal {
    private val value: NSDecimalNumber
    actual constructor(value: String) {
        this.value = NSDecimalNumber(value)
    }
    // ... implementation
}

Decision Patterns

Ask for each declaration: 1. Used by 2+ platforms? → YES (otherwise platform-specific) 2. Pure Kotlin possible? → NO (otherwise commonMain) 3. Varies by platform? → YES (expect/actual) 4. JVM-only library? → NO (otherwise jvmAndroid)

Source Set Hierarchy in Amethyst

Visual guide to source set organization with concrete examples from the codebase.

Hierarchy Diagram

┌─────────────────────────────────────────────────────────────┐
│                       commonMain                            │
│  Pure Kotlin, no platform APIs                             │
│  Examples:                                                  │
│  - Nostr event parsing (TextNoteEvent, MetadataEvent)      │
│  - Business logic (data validation, crypto algorithms)     │
│  - Data models (@Immutable data classes)                   │
│  Dependencies: kotlin-stdlib, kotlinx-coroutines           │
└──────────────────────┬──────────────────────────────────────┘
                       │
          ┌────────────┴────────────┬───────────────┐
          │                         │               │
          ▼                         ▼               ▼
┌──────────────────┐    ┌───────────────────┐   ┌──────────────┐
│   jvmAndroid     │    │     iosMain       │   │  Future:     │
│  JVM libraries   │    │   iOS common      │   │  jsMain      │
│  Examples:       │    │   Examples:       │   │  wasmMain    │
│  - Jackson JSON  │    │   - Platform API  │   └──────────────┘
│  - OkHttp HTTP   │    │   - Actuals for   │
│  - url-detector  │    │     crypto/I/O    │
│  Dependencies:   │    │   Dependencies:   │
│  - Jackson       │    │   - Platform libs │
│  - OkHttp        │    └───────┬───────────┘
└────┬─────────┬───┘            │
     │         │                │
     │         │                ├─→ iosArm64Main (device ARM64)
     │         │                └─→ iosSimulatorArm64Main (Apple Silicon)
     ▼         ▼
┌──────────┐ ┌───────────┐
│android   │ │  jvmMain  │
│Main      │ │ (Desktop) │
│Examples: │ │ Examples: │
│- Activity│ │- Window   │
│- ViewModel│ │- MenuBar  │
│- Android │ │- Desktop  │
│  APIs    │ │  Compose  │
│Deps:     │ │ Deps:     │
│- secp256k│ │- secp256k │
│  1-android│ │  1-jvm    │
│- androidx│ │- Compose  │
│          │ │  Desktop  │
└──────────┘ └───────────┘

Dependency Flow

Code in commonMain
  ↓ can use
Nothing (only Kotlin stdlib)

Code in jvmAndroid
  ↓ can use
commonMain + JVM libraries (Jackson, OkHttp)

Code in androidMain
  ↓ can use
commonMain + jvmAndroid + Android framework

Code in jvmMain
  ↓ can use
commonMain + jvmAndroid + JVM + Compose Desktop

Code in iosMain
  ↓ can use
commonMain + iOS platform APIs

Real Examples from Amethyst

commonMain - Pure Kotlin

File: quartz/src/commonMain/.../TextNoteEvent.kt

@Immutable
class TextNoteEvent(
    id: HexKey,
    pubKey: HexKey,
    createdAt: Long,
    tags: Array<Array<String>>,
    content: String,
    sig: HexKey,
) : BaseThreadedEvent(...) {
    // Pure Kotlin - works everywhere
    override fun indexableContent() = "Subject: " + subject() + "\n" + content
}

Why commonMain:

• Pure Kotlin code
• No platform APIs
• Data class with business logic
• Needed by all platforms

---

jvmAndroid - JVM Libraries

File: quartz/build.gradle.kts

val jvmAndroid = create("jvmAndroid") {
    dependsOn(commonMain.get())

    dependencies {
        // Normalizes URLs
        api(libs.rfc3986.normalizer)

        // Performant Parser of JSONs into Events
        api(libs.jackson.module.kotlin)

        // Parses URLs from Text
        api(libs.url.detector)

        // Websockets API
        implementation(libs.okhttp)
        implementation(libs.okhttpCoroutines)
    }
}

jvmMain { dependsOn(jvmAndroid) }      // Desktop gets Jackson, OkHttp
androidMain { dependsOn(jvmAndroid) }  // Android gets Jackson, OkHttp

Why jvmAndroid:

• Jackson, OkHttp are JVM-only libraries
• Works on Android (JVM) and Desktop (JVM)
• Does NOT work on iOS (not JVM) or web (not JVM)

Usage in code:

// Can use Jackson in jvmAndroid source set
val mapper = ObjectMapper()
val event = mapper.readValue(json, Event::class.java)

---

androidMain - Android Platform

File: amethyst/src/main/.../MainActivity.kt

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        enableEdgeToEdge()  // Android API
        super.onCreate(savedInstanceState)

        setContent {  // Compose for Android
            AmethystTheme {
                val accountStateViewModel: AccountStateViewModel = viewModel()
                AccountScreen(accountStateViewModel)
            }
        }
    }
}

Why androidMain:

• AppCompatActivity is Android framework
• Activity lifecycle Android-specific
• AndroidX libraries (viewModel())

Dependencies:

androidMain {
    dependsOn(jvmAndroid)  // Gets Jackson, OkHttp
    dependencies {
        implementation(libs.androidx.core.ktx)
        api(libs.secp256k1.kmp.jni.android)  // Android crypto
    }
}

---

jvmMain - Desktop Platform

File: desktopApp/src/jvmMain/.../Main.kt

fun main() = application {
    val windowState = rememberWindowState(
        width = 1200.dp,
        height = 800.dp
    )

    Window(  // Compose Desktop API
        onCloseRequest = ::exitApplication,
        state = windowState,
        title = "Amethyst"
    ) {
        MenuBar {  // Desktop-specific
            Menu("File") {
                Item("New Note", shortcut = KeyShortcut(Key.N, ctrl = true))
            }
        }
        NavigationRail { ... }  // Sidebar
    }
}

Why jvmMain:

• Window, MenuBar, NavigationRail are Compose Desktop
• Keyboard shortcuts desktop paradigm
• Different UX from Android (sidebar vs bottom nav)

Dependencies:

jvmMain {
    dependsOn(jvmAndroid)  // Gets Jackson, OkHttp
    dependencies {
        implementation(libs.secp256k1.kmp.jni.jvm)  // Desktop crypto
        implementation(compose.desktop.currentOs)
    }
}

---

iosMain - iOS Platform

File: quartz/build.gradle.kts

iosMain {
    dependsOn(commonMain.get())
    dependencies {
        // iOS platform dependencies
    }
}

val iosArm64Main by getting { dependsOn(iosMain.get()) }
val iosSimulatorArm64Main by getting { dependsOn(iosMain.get()) }

Why iosMain:

• iOS platform APIs
• Native crypto (Security framework)
• Different from Android/Desktop

Architecture targets:

• iosArm64Main: Device (iPhone, iPad)
• iosSimulatorArm64Main: Apple Silicon simulator

---

Build Order Matters

CRITICAL: jvmAndroid must be defined BEFORE androidMain and jvmMain:

// ✅ CORRECT ORDER
val jvmAndroid = create("jvmAndroid") { ... }
jvmMain { dependsOn(jvmAndroid) }
androidMain { dependsOn(jvmAndroid) }

// ❌ WRONG - Build error
androidMain { dependsOn(jvmAndroid) }  // jvmAndroid not defined yet!
val jvmAndroid = create("jvmAndroid") { ... }

See comment in quartz/build.gradle.kts:131:

// Must be defined before androidMain and jvmMain
val jvmAndroid = create("jvmAndroid") { ... }

Choosing the Right Source Set

Decision flowchart:

Q: Where should this code go?

├─ Pure Kotlin? (no platform APIs)
│  └─ commonMain
│
├─ JVM library? (Jackson, OkHttp)
│  └─ jvmAndroid
│
├─ Android API? (Activity, Context)
│  └─ androidMain
│
├─ Desktop API? (Window, MenuBar)
│  └─ jvmMain
│
└─ iOS API? (platform.posix, Security)
   └─ iosMain

Future: Web/wasm Source Sets

Not yet implemented, but structure would be:

commonMain
  ├─→ jsMain (JavaScript/Web)
  │    └─ JS-specific: DOM APIs, fetch
  │
  └─→ wasmMain (WebAssembly)
       └─ wasm-specific: limited APIs

Constraints:

• Cannot use jvmAndroid (Jackson, OkHttp)
• Cannot use platform.posix
• Must use pure Kotlin or web-compatible libs (ktor, kotlinx.serialization)

Summary Table

Target Compatibility Guide

Current targets (Android, JVM/Desktop, iOS) and future targets (web, wasm) with constraints.

Current Primary Targets

Android (androidMain)

Status: ✅ Mature, production-ready

Runtime: JVM (Dalvik/ART)

Available:

• Android framework (Activity, Context, Intent, etc.)
• AndroidX libraries (ViewModel, Navigation, etc.)
• JVM libraries via jvmAndroid (Jackson, OkHttp)
• Platform-specific crypto: secp256k1-kmp-jni-android (0.23.0 in libs.versions.toml)

Constraints:

• Mobile UX paradigms (bottom navigation, vertical scroll)
• Touch-first interaction
• Limited screen space
• Battery/performance constraints

Example code:

// androidMain
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        // Android-specific lifecycle
    }
}

---

JVM / Desktop (jvmMain)

Status: ✅ Active development, functional

Runtime: JVM

Available:

• Pure JVM libraries
• JVM libraries via jvmAndroid (Jackson, OkHttp)
• Compose Desktop (Window, MenuBar, etc.)
• Platform-specific crypto: secp256k1-kmp-jni-jvm (same 0.23.0 line)

Constraints:

• Desktop UX paradigms (sidebar, menus, keyboard shortcuts)
• Keyboard + mouse interaction
• Larger screen space
• Different navigation patterns (no back stack)

Example code:

// jvmMain
fun main() = application {
    Window(
        onCloseRequest = ::exitApplication,
        title = "Amethyst"
    ) {
        MenuBar { ... }  // Desktop-specific
        NavigationRail { ... }  // Sidebar
    }
}

---

iOS (iosMain + architecture targets)

Status: ✅ Mature — actively built and tested

Runtime: Native iOS

Source sets:

• iosMain (common iOS code)
• iosArm64Main (device - iPhone/iPad)
• iosSimulatorArm64Main (Apple Silicon simulator)
• iosX64Main (Intel simulator)
• macosArm64Main (host tooling / XCFramework build)

Available:

• iOS platform APIs (platform.posix, Foundation, etc.)
• Native crypto (Security framework)
• SwiftUI integration (via KMP framework)

NOT available:

• JVM libraries (Jackson, OkHttp)
• jvmAndroid source set
• JVM-specific APIs

Constraints:

• Mobile UX (similar to Android)
• Swift/Objective-C interop
• XCFramework distribution
• CocoaPods integration

Example code:

// iosMain
actual object Secp256k1Instance {
    actual fun signSchnorr(...): ByteArray {
        // Use iOS Security framework
    }
}

XCFramework setup:

// quartz/build.gradle.kts
kotlin {
    listOf(macosArm64(), iosArm64(), iosSimulatorArm64())
        .forEach { target ->
            target.binaries.framework {
                baseName = "quartz-kmpKit"
                isStatic = true
            }
        }
}

---

Future Targets

Web / JavaScript (jsMain)

Status: ❌ Not implemented, consider for future

Runtime: JavaScript (browser or Node.js)

Available:

• Kotlin/JS stdlib
• JS/DOM APIs
• kotlinx.* libraries (serialization, coroutines, datetime)
• ktor-client (HTTP)

NOT available:

• ❌ JVM libraries (Jackson, OkHttp)
• ❌ jvmAndroid source set
• ❌ platform.posix (no file system access like native)
• ❌ Blocking APIs (different async model - JS event loop)

Constraints:

• Single-threaded event loop
• No blocking calls
• Different async patterns (Promises, async/await)
• Browser security (CORS, no file system)

Migration path from current code:

Example migration:

// Current: jvmAndroid
val mapper = ObjectMapper()
val event = mapper.readValue(json, Event::class.java)

// Future: commonMain (works on web)
val json = Json { ignoreUnknownKeys = true }
val event = json.decodeFromString<Event>(jsonString)

---

WebAssembly (wasmMain)

Status: ❌ Not implemented, experimental Kotlin/Wasm

Runtime: WebAssembly

Available:

• Kotlin/Wasm stdlib
• Limited kotlinx.* libraries
• wasm-specific APIs

NOT available:

• ❌ JVM libraries
• ❌ Full platform.posix
• ❌ Many kotlinx libraries (limited wasm support)

Constraints:

• Even more limited than JS
• Experimental Kotlin support
• Limited library ecosystem

Recommendation: Focus on web (jsMain) first, wasm later.

---

Cross-Target Compatibility Matrix

Legend:

• ✅ Full support
• ⚠️ Limited/experimental
• ❌ Not available

---

Future-Proofing Recommendations

For Web Compatibility

DO:

• ✅ Use kotlinx.serialization instead of Jackson
• ✅ Use ktor-client instead of OkHttp
• ✅ Use kotlinx.datetime instead of java.time
• ✅ Use suspending functions (non-blocking)
• ✅ Keep business logic in commonMain

DON'T:

• ❌ Put JVM libraries in commonMain
• ❌ Use platform.posix for critical features
• ❌ Use blocking I/O
• ❌ Depend on threading (use coroutines)

Example:

// ❌ NOT web-compatible
// jvmAndroid
fun parseJson(json: String): Event {
    val mapper = ObjectMapper()  // Jackson - JVM only
    return mapper.readValue(json, Event::class.java)
}

// ✅ Web-compatible
// commonMain
@Serializable
data class Event(...)

fun parseJson(json: String): Event {
    return Json.decodeFromString<Event>(json)  // Works everywhere
}

Current Migration Priorities

High priority: (Needed for web) 1. Migrate Jackson → kotlinx.serialization 2. Migrate OkHttp → ktor-client 3. Move business logic to commonMain

Medium priority: (Nice to have) 1. Abstract date/time handling → kotlinx.datetime 2. Remove platform.posix usage where possible 3. Use suspending functions over blocking

Low priority: (Future optimization) 1. wasm-specific optimizations 2. Platform-specific performance tuning

---

Platform-Specific Patterns

Android vs iOS Differences

Desktop vs Mobile Differences

---

Testing Strategy

Per-Target Testing

Android:

• Unit tests: androidTest
• Instrumented: androidInstrumentedTest
• Device/emulator testing

Desktop:

• Unit tests: jvmTest
• Manual desktop app testing

iOS:

• Unit tests: iosTest (iosArm64Test, etc.)
• Simulator/device testing

Web (future):

• Unit tests: jsTest
• Browser testing (Selenium, Playwright)

Shared Testing

commonTest:

• Business logic tests
• Pure Kotlin code
• Works on all platforms

// commonTest
class EventParsingTest {
    @Test
    fun parseTextNoteEvent() {
        // Tests run on all platforms
    }
}

---

Summary

Current Focus: Android, JVM/Desktop, iOS (active development)

Future Considerations: Web (requires migration from Jackson/OkHttp)

Key Decision: Prefer kotlinx.* libraries over JVM-specific libs for future web compatibility.