Task Playbooks

Use these as practical recipes. Keep edits minimal and aligned with existing module boundaries.

Playbook A: Add or update a user-visible string

Add/update key in core/resources/src/commonMain/composeResources/values/strings.xml.
Import generated resource symbol in UI code (org.meshtastic.core.resources.<key>).
Use stringResource(Res.string.<key>) in Compose.
If the string appears in a shared dialog, prefer core:ui dialog components.
Verify no hardcoded user-facing strings were introduced.

Reference examples:

feature/node/src/androidMain/kotlin/org/meshtastic/feature/node/list/NodeListScreen.kt
core/ui/src/commonMain/kotlin/org/meshtastic/core/ui/component/AlertDialogs.kt

Implement or extend base ViewModel logic in feature/<name>/src/commonMain/....
Keep shared class free of Android framework dependencies.
Keep Android framework dependencies out of shared logic; if the module already uses Koin annotations in commonMain, keep patterns consistent and ensure app root inclusion.
Update navigation entry points in feature/*/src/androidMain/kotlin/org/meshtastic/feature/*/navigation/... to resolve ViewModels with koinViewModel().

Reference examples:

Shared base: feature/messaging/src/commonMain/kotlin/org/meshtastic/feature/messaging/MessageViewModel.kt
Shared base UI ViewModel: core/ui/src/commonMain/kotlin/org/meshtastic/core/ui/viewmodel/BaseUIViewModel.kt
Navigation usage: feature/settings/src/androidMain/kotlin/org/meshtastic/feature/settings/navigation/SettingsNavigation.kt
Desktop navigation usage: desktop/src/main/kotlin/org/meshtastic/desktop/navigation/DesktopSettingsNavigation.kt

Check gradle/libs.versions.toml for existing library and version alias.
Add new dependency to version catalog first (if truly new).
Wire implementation in the owning module (core:*, feature:*, or app) following existing architecture.
Register bindings/modules in app Koin graph where needed.
For Android system integration (WorkManager, service bootstrapping), wire via MeshUtilApplication and app-layer modules.

Reference examples:

App startup and Koin bootstrap: app/src/main/kotlin/org/meshtastic/app/MeshUtilApplication.kt
App module scan: app/src/main/kotlin/org/meshtastic/app/MainKoinModule.kt

Define/extend route keys in core:navigation.
Implement feature entry/content using Navigation 3 types (NavKey, NavBackStack, EntryProviderScope).
Add graph entries under the relevant feature module's navigation package (e.g., feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/navigation).
If the entry content depends on platform-specific UI (e.g. Activity context or specific desktop wrappers), use expect/actual declarations for the content composables.
Use backstack mutation (add, removeLastOrNull) instead of introducing controller-coupled APIs.
Verify deep-link behavior if route is externally reachable.

Reference examples:

Shared graph wiring: feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/navigation/SettingsNavigation.kt
Android specific content: feature/settings/src/androidMain/kotlin/org/meshtastic/feature/settings/navigation/SettingsMainScreen.kt
Desktop specific content: feature/settings/src/jvmMain/kotlin/org/meshtastic/feature/settings/navigation/SettingsMainScreen.kt
Feature intro graph pattern: feature/intro/src/androidMain/kotlin/org/meshtastic/feature/intro/IntroNavGraph.kt
Desktop nav shell: desktop/src/main/kotlin/org/meshtastic/desktop/ui/DesktopMainScreen.kt
Desktop nav graph assembly: desktop/src/main/kotlin/org/meshtastic/desktop/navigation/DesktopNavigation.kt

Keep shared contracts in core:ui or feature shared code.
Inject flavor/platform implementation via CompositionLocal from app.
Avoid direct dependency from shared modules to Google Maps/osmdroid/other Android SDK-only APIs.
Keep adapter types narrow and stable (interfaces, DTO-like params).

Reference examples:

Contract: core/ui/src/commonMain/kotlin/org/meshtastic/core/ui/util/MapViewProvider.kt
Provider wiring: app/src/main/kotlin/org/meshtastic/app/MainActivity.kt
Consumer side: feature/map/src/androidMain/kotlin/org/meshtastic/feature/map/MapScreen.kt

Create a platform application module (e.g., desktop/, ios/).
Copy desktop/src/main/kotlin/org/meshtastic/desktop/stub/NoopStubs.kt as the starting stub set. All repository interfaces have no-op implementations there.
Create a <Platform>KoinModule that mirrors desktop/src/main/kotlin/org/meshtastic/desktop/di/DesktopKoinModule.kt — use stubs for unimplemented interfaces, real implementations where available.
Add kotlinx-coroutines-swing (JVM/Desktop) or the equivalent platform coroutines dispatcher module. Without it, Dispatchers.Main is unavailable and any code using lifecycle.coroutineScope will crash at runtime.
Progressively replace stubs with real implementations (e.g., serial transport for desktop, CoreBluetooth for iOS).
Add <platform>() target to feature modules as needed (all core:* modules already declare jvm()).
Update CI JVM smoke compile step in .github/workflows/reusable-check.yml to include new modules.
If commonMain code fails to compile for the new target, it's a KMP migration debt — fix the shared code, not the target.

Reference examples:

Desktop stubs: desktop/src/main/kotlin/org/meshtastic/desktop/stub/NoopStubs.kt
Desktop DI: desktop/src/main/kotlin/org/meshtastic/desktop/di/DesktopKoinModule.kt
Desktop Navigation 3 shell: desktop/src/main/kotlin/org/meshtastic/desktop/ui/DesktopMainScreen.kt
Desktop nav graph entries: desktop/src/main/kotlin/org/meshtastic/desktop/navigation/DesktopNavigation.kt
Desktop shared feature wiring: feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/navigation/SettingsNavigation.kt
Desktop-specific screen: feature/settings/src/jvmMain/kotlin/org/meshtastic/feature/settings/DesktopSettingsScreen.kt
Roadmap: docs/roadmap.md