Meshtastic-Android/docs/archive/kmp-app-migration-assessment.md

# KMP Migration Assessment — App Module & Expect/Actual Evaluation

> Date: 2026-03-10

## Summary of Changes Made

### Expect/Actual Consolidation (Completed)

| Expect/Actual | Resolution | Rationale |
|---|---|---|
| `Base64Factory` | ✅ **Replaced** with pure `commonMain` using `kotlin.io.encoding.Base64` | Both Android/JVM used `java.util.Base64` — Kotlin stdlib provides a cross-platform equivalent |
| `isDebug` | ✅ **Replaced** with `commonMain` constant `false` | Both actuals returned `false`; runtime debug detection uses `BuildConfigProvider.isDebug` via DI |
| `NumberFormatter` | ✅ **Replaced** with pure Kotlin `commonMain` implementation | Both actuals used identical `String.format(Locale.ROOT, ...)` — pure math-based formatting works everywhere |
| `UrlUtils` | ✅ **Replaced** with pure Kotlin `commonMain` RFC 3986 encoder | Both actuals used `URLEncoder.encode` — simple byte-level encoding is trivially portable |
| `SfppHasher` | ✅ **Consolidated** into `jvmAndroidMain` intermediate source set | Byte-for-byte identical implementations using `java.security.MessageDigest` |
| `platformRandomBytes` | ✅ **Consolidated** into `jvmAndroidMain` intermediate source set | Byte-for-byte identical implementations using `java.security.SecureRandom` |
| `getShortDateTime` | ✅ **Consolidated** into `jvmAndroidMain` intermediate source set | Functionally identical `java.text.DateFormat` usage |

### Expect/Actual Retained (Genuinely Platform-Specific)

| Expect/Actual | Why It Must Remain |
|---|---|
| `BuildUtils` (isEmulator, sdkInt) | Android uses `Build.FINGERPRINT`/`Build.VERSION.SDK_INT`; JVM stubs return defaults |
| `CommonUri` | Android wraps `android.net.Uri`; JVM wraps `java.net.URI` — different parsing semantics |
| `CommonUri.toPlatformUri()` | Returns platform-native URI type for interop |
| `Parcelable` abstractions (6 declarations) | AIDL/Android Parcel is a fundamentally Android-only concept |
| `Location` | Android wraps `android.location.Location`; JVM is an empty stub |
| `DateFormatter` | Android uses `DateUtils`/`ContextServices.app`; JVM uses `java.time` formatters |
| `MeasurementSystem` | Android uses ICU `LocaleData` with API-level branching; JVM uses `Locale.getDefault()` |
| `NetworkUtils.isValidAddress` | Android uses `InetAddresses`/`Patterns`; JVM uses regex/`InetAddress` |
| `core:ui` expects (7 declarations) | Dynamic color, lifecycle, clipboard, HTML, toast, map, URL, QR, brightness — all genuinely platform-specific UI |

---

## App Module Evaluation — What's Left

### Already Migrated to Shared KMP Modules

The vast majority of business logic now lives in `core:*` and `feature:*` modules. The following pure passthrough wrappers have been eliminated from `:app`:

- `AndroidCompassViewModel` (was wrapping `feature:node → CompassViewModel`)
- `AndroidContactsViewModel` (was wrapping `feature:messaging → ContactsViewModel`)
- `AndroidQuickChatViewModel` (was wrapping `feature:messaging → QuickChatViewModel`)
- `AndroidSharedMapViewModel` (was wrapping `feature:map → SharedMapViewModel`)
- `AndroidFilterSettingsViewModel` (was wrapping `feature:settings → FilterSettingsViewModel`)
- `AndroidCleanNodeDatabaseViewModel` (was wrapping `feature:settings → CleanNodeDatabaseViewModel`)
- `AndroidFirmwareUpdateViewModel` (was wrapping `feature:firmware → FirmwareUpdateViewModel`)
- `AndroidIntroViewModel` (was wrapping `feature:intro → IntroViewModel`)
- `AndroidNodeListViewModel` (was wrapping `feature:node → NodeListViewModel`)
- `AndroidNodeDetailViewModel` (was wrapping `feature:node → NodeDetailViewModel`)
- `AndroidMessageViewModel` (was wrapping `feature:messaging → MessageViewModel`)

The remaining `app` ViewModels are ones with **genuine Android-specific logic**:

| App ViewModel | Shared Base Class | Extra Android Logic |
|---|---|---|
| `AndroidSettingsViewModel` | `feature:settings → SettingsViewModel` | File I/O via `android.net.Uri` |
| `AndroidRadioConfigViewModel` | `feature:settings → RadioConfigViewModel` | Location permissions, file I/O |
| `AndroidDebugViewModel` | `feature:settings → DebugViewModel` | `Locale`-aware hex formatting |
| `AndroidMetricsViewModel` | `feature:node → MetricsViewModel` | CSV export via `android.net.Uri` |

### Candidates for Migration (Medium Effort)

| Component | Current Location | Target | Blockers |
|---|---|---|---|
| `GetDiscoveredDevicesUseCase` | `app/domain/usecase/` | `core:domain` | Depends on BLE/USB/NSD discovery — needs platform abstraction |
| `UIViewModel` (266 lines) | `app/model/` | Split: shared → `core:ui`, Android → `app` | `android.net.Uri` deep links, alert management mostly portable |
| `SavedStateHandle`-driven ViewModels | `feature:messaging`, `feature:node` | Shared route-arg abstraction | Replace direct `SavedStateHandle` dependency in shared VMs with route params/interface |
| `DeviceListEntry` (sealed class) | `app/model/` | `core:model` (Ble, Tcp, Mock); `app` (Usb) | `Usb` variant needs `UsbManager`/`UsbSerialDriver` |

### Permanently Android-Only in `:app`

| Component | Reason |
|---|---|
| `MeshService` (392 lines) | Android `Service` with foreground notifications, AIDL `IBinder` |
| `MeshServiceClient` | Android `Activity` lifecycle `ServiceConnection` bindings |
| `BootCompleteReceiver` | Android `BroadcastReceiver` |
| `MeshServiceStarter` | Android service lifecycle management |
| `MarkAsReadReceiver`, `ReplyReceiver`, `ReactionReceiver` | Android notification action receivers |
| `MeshLogCleanupWorker`, `ServiceKeepAliveWorker` | Android `WorkManager` workers |
| `LocalStatsWidget*` | Android Glance widget |
| `AppKoinModule`, `NetworkModule`, `FlavorModule` | Android-specific DI assembly with `ConnectivityManager`, `NsdManager`, `ImageLoader`, etc. |
| `MainActivity`, `MeshUtilApplication` | Android entry points |
| `repository/radio/*` (22 files) | USB serial, BLE interface, NSD discovery — hardware-level Android APIs |
| `repository/usb/*` | `UsbSerialDriver`, `ProbeTableProvider` |
| `*Navigation.kt` (7 files) | Android Navigation 3 composable wiring |

---

## Desktop Module (formerly `jvm_demo`)

### Changes Made
- **Renamed** `:jvm_demo` → `:desktop` as the first full non-Android target
- **Added** Compose Desktop (JetBrains Compose) with Material 3 windowed UI
- **Registered** `:desktop` in `settings.gradle.kts`
- **Added** dependencies on all core KMP modules with JVM targets, including `core:ui`
- **Implemented** Koin DI bootstrap with `BuildConfigProvider` stub
- **Implemented** `DemoScenario.renderReport()` exercising Base64, NumberFormatter, UrlUtils, DateFormatter, CommonUri, DeviceVersion, Capabilities, SfppHasher, platformRandomBytes, getShortDateTime, Channel key generation
- **Implemented** JUnit tests validating report output
- **Implemented** Navigation 3 shell with `NavigationRail` + `NavDisplay` + `SavedStateConfiguration`
- **Wired** `feature:settings` with ~30 real composable screens via `DesktopSettingsNavigation.kt`
- **Created** desktop-specific `DesktopSettingsScreen.kt` (replaces Android-only `SettingsScreen`)

### Roadmap for Desktop
1. ~~Implement real navigation with shared `core:navigation` keys~~ ✅
2. ~~Wire `feature:settings` with real composables~~ ✅ (~30 screens)
3. Wire `feature:node` and `feature:messaging` composables into the desktop nav graph
4. Add serial/USB transport for direct radio connection on Desktop
5. Add MQTT transport for cloud-connected operation
6. Package native distributions (DMG, MSI, DEB)

---

## Architecture Improvement: `jvmAndroidMain` Source Set

Added `jvmAndroidMain` intermediate source sets to `core:common` and `core:model` for sharing JVM-specific code (like `java.security.*` usage) between the `androidMain` and `jvmMain` targets without duplication.

```
commonMain
    └── jvmAndroidMain     ← NEW: shared JVM code
            ├── androidMain
            └── jvmMain
```

This pattern should be adopted by other modules as they add JVM targets to eliminate duplicate actual implementations.