From da11703ccd370c071ed838545f8f9de08c0b07b9 Mon Sep 17 00:00:00 2001 From: James Rich <2199651+jamesarich@users.noreply.github.com> Date: Fri, 13 Mar 2026 11:38:25 -0500 Subject: [PATCH] ai: Establish conductor documentation and governance framework (#4780) Signed-off-by: James Rich <2199651+jamesarich@users.noreply.github.com> --- .github/copilot-instructions.md | 285 ++++++--------- AGENTS.md | 117 +++--- GEMINI.md | 141 ++++---- .../archive/desktop_parity_20260311/index.md | 5 + .../desktop_parity_20260311/metadata.json | 8 + .../archive/desktop_parity_20260311/plan.md | 41 +++ .../archive/desktop_parity_20260311/spec.md | 25 ++ .../doc_consolidation_20260311/index.md | 5 + .../doc_consolidation_20260311/metadata.json | 8 + .../doc_consolidation_20260311/plan.md | 35 ++ .../doc_consolidation_20260311/spec.md | 13 + .../index.md | 5 + .../metadata.json | 8 + .../plan.md | 37 ++ .../spec.md | 22 ++ .../archive/kmp_doc_review_20260313/index.md | 5 + .../kmp_doc_review_20260313/metadata.json | 8 + .../archive/kmp_doc_review_20260313/plan.md | 23 ++ .../archive/kmp_doc_review_20260313/spec.md | 24 ++ conductor/code_styleguides/general.md | 23 ++ conductor/doc-consolidation-plan.md | 53 +++ conductor/index.md | 14 + conductor/product-guidelines.md | 19 + conductor/product.md | 24 ++ conductor/tech-stack.md | 23 ++ conductor/tracks.md | 3 + conductor/workflow.md | 333 ++++++++++++++++++ .../BUILD_LOGIC_OPTIMIZATIONS_COMPLETE.md | 0 .../BUILD_LOGIC_OPTIMIZATION_ANALYSIS.md | 0 .../BUILD_LOGIC_OPTIMIZATION_SUMMARY.md | 0 docs/kmp-status.md | 9 + 31 files changed, 1027 insertions(+), 289 deletions(-) create mode 100644 conductor/archive/desktop_parity_20260311/index.md create mode 100644 conductor/archive/desktop_parity_20260311/metadata.json create mode 100644 conductor/archive/desktop_parity_20260311/plan.md create mode 100644 conductor/archive/desktop_parity_20260311/spec.md create mode 100644 conductor/archive/doc_consolidation_20260311/index.md create mode 100644 conductor/archive/doc_consolidation_20260311/metadata.json create mode 100644 conductor/archive/doc_consolidation_20260311/plan.md create mode 100644 conductor/archive/doc_consolidation_20260311/spec.md create mode 100644 conductor/archive/extract_hardware_transport_20260311/index.md create mode 100644 conductor/archive/extract_hardware_transport_20260311/metadata.json create mode 100644 conductor/archive/extract_hardware_transport_20260311/plan.md create mode 100644 conductor/archive/extract_hardware_transport_20260311/spec.md create mode 100644 conductor/archive/kmp_doc_review_20260313/index.md create mode 100644 conductor/archive/kmp_doc_review_20260313/metadata.json create mode 100644 conductor/archive/kmp_doc_review_20260313/plan.md create mode 100644 conductor/archive/kmp_doc_review_20260313/spec.md create mode 100644 conductor/code_styleguides/general.md create mode 100644 conductor/doc-consolidation-plan.md create mode 100644 conductor/index.md create mode 100644 conductor/product-guidelines.md create mode 100644 conductor/product.md create mode 100644 conductor/tech-stack.md create mode 100644 conductor/tracks.md create mode 100644 conductor/workflow.md rename docs/{ => archive}/BUILD_LOGIC_OPTIMIZATIONS_COMPLETE.md (100%) rename docs/{ => archive}/BUILD_LOGIC_OPTIMIZATION_ANALYSIS.md (100%) rename docs/{ => archive}/BUILD_LOGIC_OPTIMIZATION_SUMMARY.md (100%) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 492960e65..1e7418801 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,203 +1,126 @@ -# Copilot Instructions for Meshtastic-Android +# Meshtastic Android - Agent Guide -## Repository Summary +This file serves as a comprehensive guide for AI agents and developers working on the `Meshtastic-Android` codebase. Use this as your primary reference for understanding the architecture, conventions, and strict rules of this project. -Meshtastic-Android is a native Android client application for the Meshtastic mesh networking project. It enables users to communicate via off-grid, decentralized mesh networks using LoRa radios. The app is written in Kotlin and follows modern Android development practices. +For execution-focused recipes, see `docs/agent-playbooks/README.md`. -**Key Repository Details:** -- **Language:** Kotlin (primary), with some Java and AIDL files -- **Build System:** Gradle with Kotlin DSL -- **Architecture shape:** Android app shell plus a broad `core:*` / `feature:*` KMP module graph -- **Target Platform:** Android API 26+ (Android 8.0+), targeting API 36 -- **Architecture:** Android-first Kotlin Multiplatform with Jetpack Compose, Koin DI, Room KMP, DataStore, and Navigation 3 shared backstack state -- **Product Flavors:** `fdroid` (F-Droid) and `google` (Google Play Store) -- **Build Types:** `debug` and `release` +## 1. Project Vision & Architecture +Meshtastic-Android is a Kotlin Multiplatform (KMP) application for off-grid, decentralized mesh networks. The goal is to decouple business logic from the Android framework, enabling future expansion to iOS and other platforms while maintaining a high-performance native Android experience. -## Essential Build & Test Commands +- **Language:** Kotlin (primary), AIDL. +- **Build System:** Gradle (Kotlin DSL). JDK 17 is REQUIRED. +- **Target SDK:** API 36. Min SDK: API 26 (Android 8.0). +- **Flavors:** + - `fdroid`: Open source only, no tracking/analytics. + - `google`: Includes Google Play Services (Maps) and DataDog analytics. +- **Core Architecture:** Modern Android Development (MAD) with KMP core. + - **KMP Modules:** Most `core:*` modules. All declare `jvm()` target and compile clean on JVM. + - **Android-only Modules:** `core:api` (AIDL), `core:barcode` (CameraX + flavor-specific decoder). Shared contracts abstracted into `core:ui/commonMain`. + - **UI:** Jetpack Compose (Material 3). + - **DI:** Koin Annotations with K2 compiler plugin. Root graph assembly is centralized in `app`. + - **Navigation:** AndroidX Navigation 3 (JetBrains multiplatform fork) with shared backstack state. + - **Lifecycle:** JetBrains multiplatform `lifecycle-viewmodel-compose` and `lifecycle-runtime-compose`. + - **Database:** Room KMP. -**ALWAYS run these commands in the exact order specified to avoid build failures:** +## 2. Codebase Map -### Prerequisites Setup -1. **JDK Requirement:** JDK 17 is required (compatible with most developer environments) -2. **Secrets Configuration:** Copy `secrets.defaults.properties` to `local.properties` and update: +| Directory | Description | +| :--- | :--- | +| `app/` | Main application module. Contains `MainActivity`, Koin DI modules, and app-level logic. Uses package `org.meshtastic.app`. | +| `build-logic/` | Convention plugins for shared build configuration (e.g., `meshtastic.kmp.library`, `meshtastic.koin`). | +| `config/` | Detekt static analysis rules (`config/detekt/detekt.yml`) and Spotless formatting config (`config/spotless/.editorconfig`). | +| `docs/` | Architecture docs and agent playbooks. See `docs/agent-playbooks/README.md` for version baseline and task recipes. | +| `core/model` | Domain models and common data structures. | +| `core:proto` | Protobuf definitions (Git submodule). | +| `core:common` | Low-level utilities, I/O abstractions (Okio), and common types. | +| `core:database` | Room KMP database implementation. | +| `core:datastore` | Multiplatform DataStore for preferences. | +| `core:repository` | High-level domain interfaces (e.g., `NodeRepository`, `LocationRepository`). | +| `core:domain` | Pure KMP business logic and UseCases. | +| `core:data` | Core manager implementations and data orchestration. | +| `core:network` | KMP networking layer using Ktor, MQTT abstractions, and shared transport (`StreamFrameCodec` in commonMain, `TcpTransport` in jvmAndroidMain). | +| `core:di` | Common DI qualifiers and dispatchers. | +| `core:navigation` | Shared navigation keys/routes for Navigation 3. | +| `core:ui` | Shared Compose UI components (`EmptyDetailPlaceholder`, `MainAppBar`, dialogs, preferences) and platform abstractions. | +| `core:service` | KMP service layer; Android bindings stay in `androidMain`. | +| `core:api` | Public AIDL/API integration module for external clients. | +| `core:prefs` | KMP preferences layer built on DataStore abstractions. | +| `core:barcode` | Barcode scanning (Android-only). | +| `core:nfc` | NFC abstractions (KMP). Android NFC hardware implementation in `androidMain`. | +| `core/ble/` | Bluetooth Low Energy stack using Nordic libraries. | +| `core/resources/` | Centralized string and image resources (Compose Multiplatform). | +| `core/testing/` | **Shared test doubles, fakes, and utilities for `commonTest` across all KMP modules.** | +| `feature/` | Feature modules (e.g., `settings`, `map`, `messaging`, `node`, `intro`, `connections`). All are KMP with `jvm()` target. | +| `desktop/` | Compose Desktop application — first non-Android KMP target. Nav 3 shell, full Koin DI graph, TCP transport with `want_config` handshake. | +| `mesh_service_example/` | Sample app showing `core:api` service integration. | + +## 3. Development Guidelines & Coding Standards + +### A. UI Development (Jetpack Compose) +- **Material 3:** The app uses Material 3. +- **Strings:** MUST use the **Compose Multiplatform Resource** library in `core:resources` (`stringResource(Res.string.your_key)`). NEVER use hardcoded strings. +- **Dialogs:** Use centralized components in `core:ui` (e.g., `MeshtasticResourceDialog`). +- **Platform/Flavor UI:** Inject platform-specific behavior (e.g., map providers) via `CompositionLocal` from `app`. + +### B. Logic & Data Layer +- **KMP Focus:** All business logic must reside in `commonMain` of the respective `core` module. +- **Platform purity:** Never import `java.*` or `android.*` in `commonMain`. Use KMP alternatives: + - `java.util.Locale` → Kotlin `uppercase()` / `lowercase()` or `expect`/`actual`. + - `java.util.concurrent.ConcurrentHashMap` → `atomicfu` or `Mutex`-guarded `mutableMapOf()`. + - `java.util.concurrent.locks.*` → `kotlinx.coroutines.sync.Mutex`. + - `java.io.*` → Okio (`BufferedSource`/`BufferedSink`). +- **Concurrency:** Use Kotlin Coroutines and Flow. +- **Dependency Injection:** Use **Koin Annotations** with the K2 compiler plugin (0.4.0+). Keep root graph assembly in `app`. +- **ViewModels:** Follow the MVI/UDF pattern. Use the multiplatform `androidx.lifecycle.ViewModel` in `commonMain`. +- **BLE:** All Bluetooth communication must route through `core:ble` using Nordic Semiconductor's Android Common Libraries. +- **Dependencies:** Check `gradle/libs.versions.toml` before assuming a library is available. +- **Room KMP:** Always use `factory = { MeshtasticDatabaseConstructor.initialize() }` in `Room.databaseBuilder` and `inMemoryDatabaseBuilder`. DAOs and Entities reside in `commonMain`. +- **Testing:** Write ViewModel and business logic tests in `commonTest`. Use `core:testing` shared fakes. + +### C. Namespacing +- **Standard:** Use the `org.meshtastic.*` namespace for all code. +- **Legacy:** Maintain the `com.geeksville.mesh` Application ID. + +## 4. Execution Protocol + +### A. Environment Setup +1. **JDK 17 MUST be used** to prevent Gradle sync/build failures. +2. **Secrets:** You must copy `secrets.defaults.properties` to `local.properties`: ```properties - MAPS_API_KEY=your_google_maps_api_key_here - datadogApplicationId=your_datadog_app_id - datadogClientToken=your_datadog_client_token + MAPS_API_KEY=dummy_key + datadogApplicationId=dummy_id + datadogClientToken=dummy_token ``` -3. **Clean Environment:** Always start with `./gradlew clean` for fresh builds -### Build Commands (Validated Working Order) +### B. Strict Execution Commands +Always run commands in the following order to ensure reliability. Do not attempt to bypass `clean` if you are facing build issues. + +**Baseline (recommended order):** ```bash -# 1. ALWAYS clean first for reliable builds ./gradlew clean - -# 2. Check code formatting (run before making changes) ./gradlew spotlessCheck - -# 3. Apply automatic code formatting fixes ./gradlew spotlessApply - -# 4. Run static code analysis/linting ./gradlew detekt - -# 5. Build debug APKs for both flavors (takes 3-5 minutes) ./gradlew assembleDebug - -# 6. Build specific flavor variants -./gradlew assembleFdroidDebug # F-Droid debug build -./gradlew assembleGoogleDebug # Google debug build -./gradlew assembleFdroidRelease # F-Droid release build -./gradlew assembleGoogleRelease # Google release build - -# 7. Run local unit tests (takes 2-3 minutes) ./gradlew test - -# 8. Run specific flavor unit tests -./gradlew testFdroidDebug -./gradlew testGoogleDebug - -# 9. Run instrumented tests (requires Android device/emulator, takes 5-10 minutes) -./gradlew connectedAndroidTest - -# 10. Run lint checks for both flavors -./gradlew lintFdroidDebug lintGoogleDebug - -# 11. Run the desktop module -./gradlew :desktop:run -./gradlew :desktop:test -- Clean build: 3-5 minutes -- Unit tests: 2-3 minutes -- Instrumented tests: 5-10 minutes -- Detekt analysis: 1-2 minutes -- Spotless formatting: 30 seconds - -### Environment Setup -**Required Tools:** -- Android SDK API 36 (compile target) -- JDK 17 (Preferred for consistency across project and plugins) -- Gradle 9.0+ (downloaded automatically by wrapper) - -**Optional but Recommended:** -- Install pre-push Git hook: `./gradlew spotlessInstallGitPrePushHook --no-configuration-cache` - -## Project Architecture & Layout - -### Module Structure -``` -├── app/ # Main Android application -│ ├── src/main/ # Main source code -│ ├── src/test/ # Unit tests -│ ├── src/androidTest/ # Instrumented tests -│ ├── src/fdroid/ # F-Droid specific code -│ └── src/google/ # Google Play specific code -├── core/ # Core library modules -├── desktop/ # Compose Desktop application (first non-Android KMP target) -├── feature/ # Feature modules (all KMP with JVM targets) -│ ├── connections/ # Device connections UI (BLE, TCP, USB scanning) -│ ├── firmware/ # Firmware update flow -│ ├── intro/ # Onboarding flow -│ ├── map/ # Map UI -│ ├── messaging/ # Messaging/contacts UI -│ ├── node/ # Node list and detail UI -│ └── settings/ # Settings screens -├── build-logic/ # Build configuration convention plugins -└── config/ # Linting and formatting configs - ├── detekt/ # Detekt static analysis rules - └── spotless/ # Code formatting configuration ``` -### Key Configuration Files -- `config.properties` - Version constants and build config -- `app/build.gradle.kts` - Main app build configuration -- `config/detekt/detekt.yml` - Static analysis rules -- `config/spotless/.editorconfig` - Code formatting rules -- `gradle.properties` - Gradle build settings -- `secrets.defaults.properties` - Template for secrets (copy to `local.properties`) - -### Architecture Components -- **UI Framework:** Jetpack Compose with Material 3 -- **State Management:** Unidirectional Data Flow with ViewModels -- **Dependency Injection:** Koin Annotations with K2 compiler plugin -- **Navigation:** AndroidX Navigation 3 (JetBrains multiplatform fork) with shared navigation keys/routes in `core:navigation` -- **Lifecycle:** JetBrains multiplatform forks for `lifecycle-viewmodel-compose` and `lifecycle-runtime-compose` -- **Local Data:** Room database + DataStore preferences -- **Remote Data:** Shared BLE/network/service layers across `core:ble`, `core:network`, and `core:service` -- **Background Work:** WorkManager -- **Communication:** AIDL service interface (`IMeshService.aidl`) -- **Desktop:** First non-Android KMP target. Nav 3 shell, full Koin DI, TCP transport with `want_config` handshake, adaptive list-detail screens for nodes/messaging, ~35 settings screens, connections UI. See `docs/kmp-status.md`. - -## Continuous Integration - -### GitHub Workflows (.github/workflows/) -- **pull-request.yml** - PR entry workflow -- **reusable-check.yml** - Shared Android/JVM verification: spotless, detekt, unit tests, Kover, JVM smoke compile, assemble/lint, optional instrumented tests - -### CI Commands (Must Pass) +**Testing:** ```bash -# Reusable CI workflow runs these core checks on the first matrix leg: -./gradlew spotlessCheck detekt -Pci=true -./gradlew testDebugUnitTest testFdroidDebugUnitTest testGoogleDebugUnitTest koverXmlReport app:koverXmlReportFdroidDebug app:koverXmlReportGoogleDebug -Pci=true --continue -./gradlew :core:proto:compileKotlinJvm :core:common:compileKotlinJvm :core:model:compileKotlinJvm :core:repository:compileKotlinJvm :core:di:compileKotlinJvm :core:navigation:compileKotlinJvm :core:resources:compileKotlinJvm :core:datastore:compileKotlinJvm :core:database:compileKotlinJvm :core:domain:compileKotlinJvm :core:prefs:compileKotlinJvm :core:network:compileKotlinJvm :core:data:compileKotlinJvm :core:ble:compileKotlinJvm :core:nfc:compileKotlinJvm :core:service:compileKotlinJvm :core:ui:compileKotlinJvm :feature:intro:compileKotlinJvm :feature:messaging:compileKotlinJvm :feature:connections:compileKotlinJvm :feature:map:compileKotlinJvm :feature:node:compileKotlinJvm :feature:settings:compileKotlinJvm :feature:firmware:compileKotlinJvm :desktop:test -Pci=true --continue +./gradlew test # Run local unit tests +./gradlew testDebugUnitTest # CI-aligned Android unit tests +./gradlew connectedAndroidTest # Run instrumented tests +./gradlew testFdroidDebug testGoogleDebug # Flavor-specific unit tests +./gradlew lintFdroidDebug lintGoogleDebug # Flavor-specific lint checks ``` +*Note: If testing Compose UI on the JVM (Robolectric) with Java 17, pin your tests to `@Config(sdk = [34])` to avoid SDK 35 compatibility crashes.* -### Validation Steps -1. **Code Style:** Spotless check (auto-fixable with `spotlessApply`) -2. **Static Analysis:** Detekt with custom rules in `config/detekt/detekt.yml` -3. **Shared smoke compile:** JVM compile checks for all `core:*` and `feature:*` KMP modules plus `:desktop:test` -4. **Lint Checks:** Android lint on debug variants -5. **Unit Tests:** Android/unit/shared tests plus Kover reports -6. **UI Tests:** Compose/instrumented tests when emulator runs are enabled +### C. Documentation Sync +Update documentation continuously as part of the same change. If you modify architecture, module targets, CI tasks, validation commands, or agent workflow rules, update the relevant docs (`AGENTS.md`, `.github/copilot-instructions.md`, `GEMINI.md`, `docs/agent-playbooks/*`, `docs/kmp-status.md`, and `docs/decisions/architecture-review-2026-03.md`). -## Common Issues & Solutions - -### Build Failures -- **Gradle version error:** Ensure JDK 17 (Compatible version) -- **Missing secrets:** Copy `secrets.defaults.properties` → `local.properties` -- **Configuration cache:** Add `--no-configuration-cache` flag if issues persist -- **Clean state:** Always run `./gradlew clean` before debugging build issues - -### Desktop Issues -- **`Dispatchers.Main` missing:** JVM/Desktop requires `kotlinx-coroutines-swing` for `Dispatchers.Main`. Without it, any code using `lifecycle.coroutineScope` or `Dispatchers.Main` will crash at runtime. The desktop module already includes this dependency. - -### Testing Issues -- **Instrumented tests:** Require Android device/emulator with API 26+ -- **UI tests:** Use `ComposeTestRule` for Compose UI testing -- **Coroutine tests:** Use `kotlinx.coroutines.test` library - -### Code Style Issues -- **Formatting:** Run `./gradlew spotlessApply` to auto-fix -- **Detekt warnings:** Check `config/detekt/detekt.yml` for rules -- **Localization:** Use `stringResource(Res.string.key)` instead of hardcoded strings - -## File Organization - -### Source Code Locations -- **Main Activity:** `app/src/main/kotlin/org/meshtastic/app/MainActivity.kt` -- **Service Interface:** `core/api/src/main/aidl/org/meshtastic/core/service/IMeshService.aidl` -- **Shared feature/UI code:** `feature/*/src/commonMain/kotlin/org/meshtastic/feature/*/` -- **Data Layer:** `core/data/src/commonMain/kotlin/org/meshtastic/core/data/` -- **Database:** `core/database/src/commonMain/kotlin/org/meshtastic/core/database/` -- **Models:** `core/model/src/commonMain/kotlin/org/meshtastic/core/model/` - -### Dependencies -- **Non-obvious deps:** Protobuf for device communication, DataDog for analytics (Google flavor) -- **Flavor-specific:** Google Services (google flavor), no analytics (fdroid flavor) -- **Version catalog:** Dependencies defined in `gradle/libs.versions.toml` - -## Agent Instructions - -- Keep documentation continuously in sync with the code. If you change architecture, module targets, CI tasks, validation commands, or agent workflow rules, update the relevant docs in the same change. -- Treat `AGENTS.md` as the primary source of truth for project architecture and process; update mirrored guidance here when that source changes. -- Architecture review and gap analysis: `docs/decisions/architecture-review-2026-03.md`. -- **Platform purity:** Never import `java.*` or `android.*` in `commonMain`. Use KMP alternatives (see AGENTS.md §3B for the full list). -- **Testing:** Write ViewModel and business logic tests in `commonTest` (not `test/` Robolectric) so every target runs them. - -**TRUST THESE INSTRUCTIONS** - they are validated and comprehensive. Only search for additional information if: -1. Commands fail with unexpected errors -2. Information appears outdated -3. Working on areas not covered above - -**Always prefer:** Using the documented commands over exploring alternatives, as they are tested and proven to work in the CI environment. - -**For code changes:** Follow the architecture patterns established in existing code, maintain the modular structure, and ensure all validation steps pass before submitting changes. \ No newline at end of file +## 5. Troubleshooting +- **Build Failures:** Check `gradle/libs.versions.toml` for dependency conflicts. +- **Missing Secrets:** Check `local.properties`. +- **JDK Version:** JDK 17 is required. +- **Configuration Cache:** Add `--no-configuration-cache` flag if cache-related issues persist. +- **Koin Injection Failures:** Verify the KMP component is included in `app` root module wiring (`AppKoinModule`). \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 18b17fc54..1e7418801 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,8 +4,23 @@ This file serves as a comprehensive guide for AI agents and developers working o For execution-focused recipes, see `docs/agent-playbooks/README.md`. -## 1. Project Vision -We are incrementally migrating Meshtastic-Android to a **Kotlin Multiplatform (KMP)** architecture. The goal is to decouple business logic from the Android framework, enabling future expansion to iOS and other platforms while maintaining a high-performance native Android experience. +## 1. Project Vision & Architecture +Meshtastic-Android is a Kotlin Multiplatform (KMP) application for off-grid, decentralized mesh networks. The goal is to decouple business logic from the Android framework, enabling future expansion to iOS and other platforms while maintaining a high-performance native Android experience. + +- **Language:** Kotlin (primary), AIDL. +- **Build System:** Gradle (Kotlin DSL). JDK 17 is REQUIRED. +- **Target SDK:** API 36. Min SDK: API 26 (Android 8.0). +- **Flavors:** + - `fdroid`: Open source only, no tracking/analytics. + - `google`: Includes Google Play Services (Maps) and DataDog analytics. +- **Core Architecture:** Modern Android Development (MAD) with KMP core. + - **KMP Modules:** Most `core:*` modules. All declare `jvm()` target and compile clean on JVM. + - **Android-only Modules:** `core:api` (AIDL), `core:barcode` (CameraX + flavor-specific decoder). Shared contracts abstracted into `core:ui/commonMain`. + - **UI:** Jetpack Compose (Material 3). + - **DI:** Koin Annotations with K2 compiler plugin. Root graph assembly is centralized in `app`. + - **Navigation:** AndroidX Navigation 3 (JetBrains multiplatform fork) with shared backstack state. + - **Lifecycle:** JetBrains multiplatform `lifecycle-viewmodel-compose` and `lifecycle-runtime-compose`. + - **Database:** Room KMP. ## 2. Codebase Map @@ -26,80 +41,86 @@ We are incrementally migrating Meshtastic-Android to a **Kotlin Multiplatform (K | `core:network` | KMP networking layer using Ktor, MQTT abstractions, and shared transport (`StreamFrameCodec` in commonMain, `TcpTransport` in jvmAndroidMain). | | `core:di` | Common DI qualifiers and dispatchers. | | `core:navigation` | Shared navigation keys/routes for Navigation 3. | -| `core:ui` | Shared Compose UI components (`EmptyDetailPlaceholder`, `MainAppBar`, dialogs, preferences) and platform abstractions, including `jvmAndroidMain` bridges for shared JVM/Android actuals. | +| `core:ui` | Shared Compose UI components (`EmptyDetailPlaceholder`, `MainAppBar`, dialogs, preferences) and platform abstractions. | | `core:service` | KMP service layer; Android bindings stay in `androidMain`. | | `core:api` | Public AIDL/API integration module for external clients. | | `core:prefs` | KMP preferences layer built on DataStore abstractions. | -| `core:barcode` | Barcode scanning (Android-only). Shared UI in `main/`; only the decoder (`createBarcodeAnalyzer`) differs per flavor (ML Kit / ZXing). Shared contract in `core:ui`. | -| `core:nfc` | NFC abstractions (KMP). Android NFC hardware implementation in `androidMain`; shared contract via `LocalNfcScannerProvider` in `core:ui`. | +| `core:barcode` | Barcode scanning (Android-only). | +| `core:nfc` | NFC abstractions (KMP). Android NFC hardware implementation in `androidMain`. | | `core/ble/` | Bluetooth Low Energy stack using Nordic libraries. | | `core/resources/` | Centralized string and image resources (Compose Multiplatform). | -| `core/testing/` | **Shared test doubles, fakes, and utilities for `commonTest` across all KMP modules.** Lightweight with minimal dependencies (only `core:model`, `core:repository`, + test libs). Keeps module dependency graph clean by centralizing test consolidation. See `core/testing/README.md`. | +| `core/testing/` | **Shared test doubles, fakes, and utilities for `commonTest` across all KMP modules.** | | `feature/` | Feature modules (e.g., `settings`, `map`, `messaging`, `node`, `intro`, `connections`). All are KMP with `jvm()` target. | -| `feature/connections` | Connections UI — device discovery, BLE/TCP/USB scanning, shared composables in `commonMain`; Android BLE bonding/NSD/USB in `androidMain`. | -| `feature/firmware` | Firmware update flow (KMP module with Android DFU in `androidMain`). | -| `desktop/` | Compose Desktop application — first non-Android KMP target. Nav 3 shell, full Koin DI graph, TCP transport with `want_config` handshake, adaptive list-detail screens for nodes/messaging, ~35 real settings screens, connections UI. See `docs/kmp-status.md`. | +| `desktop/` | Compose Desktop application — first non-Android KMP target. Nav 3 shell, full Koin DI graph, TCP transport with `want_config` handshake. | | `mesh_service_example/` | Sample app showing `core:api` service integration. | -## 3. Development Guidelines +## 3. Development Guidelines & Coding Standards ### A. UI Development (Jetpack Compose) - **Material 3:** The app uses Material 3. -- **Strings:** - - **Rule:** MUST use the **Compose Multiplatform Resource** library in `core:resources`. - - **Location:** `core/resources/src/commonMain/composeResources/values/strings.xml`. -- **Dialogs:** Use centralized components in `core:ui`. -- **Platform/Flavor UI:** Inject platform-specific behavior (e.g., map providers) via `CompositionLocal` from `app`. See `core/ui/src/commonMain/kotlin/org/meshtastic/core/ui/util/MapViewProvider.kt` for the contract pattern and `app/src/main/kotlin/org/meshtastic/app/MainActivity.kt` for provider wiring. +- **Strings:** MUST use the **Compose Multiplatform Resource** library in `core:resources` (`stringResource(Res.string.your_key)`). NEVER use hardcoded strings. +- **Dialogs:** Use centralized components in `core:ui` (e.g., `MeshtasticResourceDialog`). +- **Platform/Flavor UI:** Inject platform-specific behavior (e.g., map providers) via `CompositionLocal` from `app`. ### B. Logic & Data Layer - **KMP Focus:** All business logic must reside in `commonMain` of the respective `core` module. - **Platform purity:** Never import `java.*` or `android.*` in `commonMain`. Use KMP alternatives: - - `java.util.Locale` → Kotlin `uppercase()` / `lowercase()` (locale-independent for ASCII) or `expect`/`actual`. + - `java.util.Locale` → Kotlin `uppercase()` / `lowercase()` or `expect`/`actual`. - `java.util.concurrent.ConcurrentHashMap` → `atomicfu` or `Mutex`-guarded `mutableMapOf()`. - `java.util.concurrent.locks.*` → `kotlinx.coroutines.sync.Mutex`. - `java.io.*` → Okio (`BufferedSource`/`BufferedSink`). -- **I/O:** Use **Okio** (`BufferedSource`/`BufferedSink`) for stream operations. Never use `java.io` in `commonMain`. - **Concurrency:** Use Kotlin Coroutines and Flow. -- **Thread-Safety:** Use `atomicfu` and `kotlinx.collections.immutable` for shared state in `commonMain`. Avoid `synchronized` or JVM-specific atomics. -- **Dependency Injection:** - - Use **Koin Annotations** with the K2 compiler plugin (0.4.0+). - - Keep root graph assembly in `app` (module inclusion in `AppKoinModule` and startup wiring in `MeshUtilApplication`). - - Use `@Module`, `@ComponentScan`, and `@KoinViewModel` annotations directly in `commonMain` shared modules. - - **Note on Koin 0.4.0 compile safety:** Koin's A1 (per-module) validation is globally disabled in `build-logic`. Because Meshtastic employs Clean Architecture dependency inversion (interfaces in `core:repository`, implementations in `core:data`), enforcing A1 resolution per-module fails. Validation occurs at the full-graph (A3) level instead. -- **ViewModels:** Follow the MVI/UDF pattern. Use the multiplatform `androidx.lifecycle.ViewModel` in `commonMain` to maintain a single source of truth for UI state, relying heavily on `StateFlow`. -- **BLE:** All Bluetooth communication must route through `core:ble` using Nordic Semiconductor's Android Common Libraries and Kotlin Coroutines/Flows. Never use legacy Android Bluetooth callbacks directly. -- **Dependencies:** Check `gradle/libs.versions.toml` before assuming a library is available. New dependencies MUST be added to the version catalog, not directly to a `build.gradle.kts` file. -- **Shared JVM + Android code:** If a KMP module needs a `jvmAndroidMain` source set for code shared between desktop JVM and Android, apply the `meshtastic.kmp.jvm.android` convention plugin. Do **not** hand-wire `sourceSets.dependsOn(...)` edges in module `build.gradle.kts` files—the convention uses Kotlin's hierarchy template API and avoids default hierarchy warnings. +- **Dependency Injection:** Use **Koin Annotations** with the K2 compiler plugin (0.4.0+). Keep root graph assembly in `app`. +- **ViewModels:** Follow the MVI/UDF pattern. Use the multiplatform `androidx.lifecycle.ViewModel` in `commonMain`. +- **BLE:** All Bluetooth communication must route through `core:ble` using Nordic Semiconductor's Android Common Libraries. +- **Dependencies:** Check `gradle/libs.versions.toml` before assuming a library is available. - **Room KMP:** Always use `factory = { MeshtasticDatabaseConstructor.initialize() }` in `Room.databaseBuilder` and `inMemoryDatabaseBuilder`. DAOs and Entities reside in `commonMain`. -- **Testing:** Write ViewModel and business logic tests in `commonTest` (not `test/` Robolectric) so every target runs them. Use `core:testing` shared fakes when available. **Test framework dependencies** (`kotlin("test")` for both `commonTest` and `androidHostTest` source sets) are automatically provided by the `meshtastic.kmp.library` convention plugin—no need to add them manually to individual module `build.gradle.kts` files. See `build-logic/convention/src/main/kotlin/org/meshtastic/buildlogic/KotlinAndroid.kt::configureKmpTestDependencies()` for details. +- **Testing:** Write ViewModel and business logic tests in `commonTest`. Use `core:testing` shared fakes. ### C. Namespacing - **Standard:** Use the `org.meshtastic.*` namespace for all code. -- **Legacy:** Maintain the `com.geeksville.mesh` Application ID and specific intent strings for backward compatibility. +- **Legacy:** Maintain the `com.geeksville.mesh` Application ID. ## 4. Execution Protocol -### A. Build and Verify -**Prerequisite:** JDK 17 is required. Copy `secrets.defaults.properties` to `local.properties` before building. -1. **Clean:** `./gradlew clean` -2. **Format:** `./gradlew spotlessCheck` then `./gradlew spotlessApply` -3. **Lint:** `./gradlew detekt` -4. **Build + Unit Tests:** `./gradlew assembleDebug test` (CI also runs `testDebugUnitTest`) -5. **Flavor/CI Parity (when relevant):** `./gradlew lintFdroidDebug lintGoogleDebug testFdroidDebug testGoogleDebug` -6. **Desktop (when touched):** `./gradlew :desktop:test :desktop:run` +### A. Environment Setup +1. **JDK 17 MUST be used** to prevent Gradle sync/build failures. +2. **Secrets:** You must copy `secrets.defaults.properties` to `local.properties`: + ```properties + MAPS_API_KEY=dummy_key + datadogApplicationId=dummy_id + datadogClientToken=dummy_token + ``` -### B. Documentation Sync -- If you change architecture, module boundaries, target declarations, CI tasks, validation commands, or agent workflow rules, update the corresponding docs in the same slice. -- KMP status: `docs/kmp-status.md`. Roadmap: `docs/roadmap.md`. Decisions: `docs/decisions/`. Architecture review: `docs/decisions/architecture-review-2026-03.md`. -- At minimum, review and update the relevant source of truth among `AGENTS.md`, `.github/copilot-instructions.md`, `GEMINI.md`, `docs/agent-playbooks/*`, and `docs/kmp-status.md` when those areas are affected. +### B. Strict Execution Commands +Always run commands in the following order to ensure reliability. Do not attempt to bypass `clean` if you are facing build issues. -### C. Expect/Actual Patterns -Use `expect`/`actual` sparingly for platform-specific types (e.g., `Location`, platform utilities) to keep core logic pure. For navigation, prefer shared Navigation 3 backstack state (`List`) over platform controller types. +**Baseline (recommended order):** +```bash +./gradlew clean +./gradlew spotlessCheck +./gradlew spotlessApply +./gradlew detekt +./gradlew assembleDebug +./gradlew test +``` + +**Testing:** +```bash +./gradlew test # Run local unit tests +./gradlew testDebugUnitTest # CI-aligned Android unit tests +./gradlew connectedAndroidTest # Run instrumented tests +./gradlew testFdroidDebug testGoogleDebug # Flavor-specific unit tests +./gradlew lintFdroidDebug lintGoogleDebug # Flavor-specific lint checks +``` +*Note: If testing Compose UI on the JVM (Robolectric) with Java 17, pin your tests to `@Config(sdk = [34])` to avoid SDK 35 compatibility crashes.* + +### C. Documentation Sync +Update documentation continuously as part of the same change. If you modify architecture, module targets, CI tasks, validation commands, or agent workflow rules, update the relevant docs (`AGENTS.md`, `.github/copilot-instructions.md`, `GEMINI.md`, `docs/agent-playbooks/*`, `docs/kmp-status.md`, and `docs/decisions/architecture-review-2026-03.md`). ## 5. Troubleshooting -- **Build Failures:** Always check `gradle/libs.versions.toml` for dependency conflicts. -- **Missing Secrets:** Copy `secrets.defaults.properties` → `local.properties` with valid (or dummy) values for `MAPS_API_KEY`, `datadogApplicationId`, and `datadogClientToken`. -- **JDK Version:** JDK 17 is required. Mismatched JDK versions cause Gradle sync/build failures. +- **Build Failures:** Check `gradle/libs.versions.toml` for dependency conflicts. +- **Missing Secrets:** Check `local.properties`. +- **JDK Version:** JDK 17 is required. - **Configuration Cache:** Add `--no-configuration-cache` flag if cache-related issues persist. -- **Koin Injection Failures:** Verify the KMP component is included in `app` root module wiring (`AppKoinModule`) and that `startKoin` loads that module at app startup. -- **Desktop `Dispatchers.Main` missing:** JVM/Desktop requires `kotlinx-coroutines-swing` for `Dispatchers.Main`. Without it, any code using `lifecycle.coroutineScope` or `Dispatchers.Main` will crash at runtime. The desktop module already includes this dependency. +- **Koin Injection Failures:** Verify the KMP component is included in `app` root module wiring (`AppKoinModule`). \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md index c333c8bc2..1e7418801 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,11 +1,11 @@ -# Meshtastic-Android: AI Agent Instructions (GEMINI.md) +# Meshtastic Android - Agent Guide -**CRITICAL AGENT DIRECTIVE:** This file contains validated, comprehensive instructions for interacting with the Meshtastic-Android repository. You MUST adhere strictly to these rules, build commands, and architectural constraints. Only deviate or explore alternatives if the documented commands fail with unexpected errors. +This file serves as a comprehensive guide for AI agents and developers working on the `Meshtastic-Android` codebase. Use this as your primary reference for understanding the architecture, conventions, and strict rules of this project. -If this file conflicts with `AGENTS.md`, follow `AGENTS.md`. +For execution-focused recipes, see `docs/agent-playbooks/README.md`. -## 1. Project Overview & Architecture -Meshtastic-Android is a Kotlin Multiplatform (KMP) application for off-grid, decentralized mesh networks. +## 1. Project Vision & Architecture +Meshtastic-Android is a Kotlin Multiplatform (KMP) application for off-grid, decentralized mesh networks. The goal is to decouple business logic from the Android framework, enabling future expansion to iOS and other platforms while maintaining a high-performance native Android experience. - **Language:** Kotlin (primary), AIDL. - **Build System:** Gradle (Kotlin DSL). JDK 17 is REQUIRED. @@ -14,27 +14,85 @@ Meshtastic-Android is a Kotlin Multiplatform (KMP) application for off-grid, dec - `fdroid`: Open source only, no tracking/analytics. - `google`: Includes Google Play Services (Maps) and DataDog analytics. - **Core Architecture:** Modern Android Development (MAD) with KMP core. - - **KMP Modules:** `core:model`, `core:proto`, `core:common`, `core:resources`, `core:database`, `core:datastore`, `core:repository`, `core:domain`, `core:prefs`, `core:network`, `core:di`, `core:data`, `core:ble`, `core:nfc`, `core:service`, `core:ui`, `core:navigation`, `core:testing`. All declare `jvm()` target and compile clean on JVM. + - **KMP Modules:** Most `core:*` modules. All declare `jvm()` target and compile clean on JVM. - **Android-only Modules:** `core:api` (AIDL), `core:barcode` (CameraX + flavor-specific decoder). Shared contracts abstracted into `core:ui/commonMain`. - **UI:** Jetpack Compose (Material 3). - - **DI:** Koin Annotations with K2 compiler plugin. Root graph assembly is centralized in `app` (`AppKoinModule` + `startKoin`), while shared modules can expose annotated definitions that are included by the app root module. - - **Navigation:** AndroidX Navigation 3 (JetBrains multiplatform fork: `org.jetbrains.androidx.navigation3`) with shared backstack state (`List`). - - **Lifecycle (multiplatform):** JetBrains forks `org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose` and `lifecycle-runtime-compose`. - - **Room KMP:** Always use `factory = { MeshtasticDatabaseConstructor.initialize() }` in `Room.databaseBuilder` and `inMemoryDatabaseBuilder`. DAOs and Entities reside in `commonMain`. + - **DI:** Koin Annotations with K2 compiler plugin. Root graph assembly is centralized in `app`. + - **Navigation:** AndroidX Navigation 3 (JetBrains multiplatform fork) with shared backstack state. + - **Lifecycle:** JetBrains multiplatform `lifecycle-viewmodel-compose` and `lifecycle-runtime-compose`. + - **Database:** Room KMP. -## 2. Environment Setup (Mandatory First Steps) -Before attempting any builds or tests, ensure the environment is configured: +## 2. Codebase Map +| Directory | Description | +| :--- | :--- | +| `app/` | Main application module. Contains `MainActivity`, Koin DI modules, and app-level logic. Uses package `org.meshtastic.app`. | +| `build-logic/` | Convention plugins for shared build configuration (e.g., `meshtastic.kmp.library`, `meshtastic.koin`). | +| `config/` | Detekt static analysis rules (`config/detekt/detekt.yml`) and Spotless formatting config (`config/spotless/.editorconfig`). | +| `docs/` | Architecture docs and agent playbooks. See `docs/agent-playbooks/README.md` for version baseline and task recipes. | +| `core/model` | Domain models and common data structures. | +| `core:proto` | Protobuf definitions (Git submodule). | +| `core:common` | Low-level utilities, I/O abstractions (Okio), and common types. | +| `core:database` | Room KMP database implementation. | +| `core:datastore` | Multiplatform DataStore for preferences. | +| `core:repository` | High-level domain interfaces (e.g., `NodeRepository`, `LocationRepository`). | +| `core:domain` | Pure KMP business logic and UseCases. | +| `core:data` | Core manager implementations and data orchestration. | +| `core:network` | KMP networking layer using Ktor, MQTT abstractions, and shared transport (`StreamFrameCodec` in commonMain, `TcpTransport` in jvmAndroidMain). | +| `core:di` | Common DI qualifiers and dispatchers. | +| `core:navigation` | Shared navigation keys/routes for Navigation 3. | +| `core:ui` | Shared Compose UI components (`EmptyDetailPlaceholder`, `MainAppBar`, dialogs, preferences) and platform abstractions. | +| `core:service` | KMP service layer; Android bindings stay in `androidMain`. | +| `core:api` | Public AIDL/API integration module for external clients. | +| `core:prefs` | KMP preferences layer built on DataStore abstractions. | +| `core:barcode` | Barcode scanning (Android-only). | +| `core:nfc` | NFC abstractions (KMP). Android NFC hardware implementation in `androidMain`. | +| `core/ble/` | Bluetooth Low Energy stack using Nordic libraries. | +| `core/resources/` | Centralized string and image resources (Compose Multiplatform). | +| `core/testing/` | **Shared test doubles, fakes, and utilities for `commonTest` across all KMP modules.** | +| `feature/` | Feature modules (e.g., `settings`, `map`, `messaging`, `node`, `intro`, `connections`). All are KMP with `jvm()` target. | +| `desktop/` | Compose Desktop application — first non-Android KMP target. Nav 3 shell, full Koin DI graph, TCP transport with `want_config` handshake. | +| `mesh_service_example/` | Sample app showing `core:api` service integration. | + +## 3. Development Guidelines & Coding Standards + +### A. UI Development (Jetpack Compose) +- **Material 3:** The app uses Material 3. +- **Strings:** MUST use the **Compose Multiplatform Resource** library in `core:resources` (`stringResource(Res.string.your_key)`). NEVER use hardcoded strings. +- **Dialogs:** Use centralized components in `core:ui` (e.g., `MeshtasticResourceDialog`). +- **Platform/Flavor UI:** Inject platform-specific behavior (e.g., map providers) via `CompositionLocal` from `app`. + +### B. Logic & Data Layer +- **KMP Focus:** All business logic must reside in `commonMain` of the respective `core` module. +- **Platform purity:** Never import `java.*` or `android.*` in `commonMain`. Use KMP alternatives: + - `java.util.Locale` → Kotlin `uppercase()` / `lowercase()` or `expect`/`actual`. + - `java.util.concurrent.ConcurrentHashMap` → `atomicfu` or `Mutex`-guarded `mutableMapOf()`. + - `java.util.concurrent.locks.*` → `kotlinx.coroutines.sync.Mutex`. + - `java.io.*` → Okio (`BufferedSource`/`BufferedSink`). +- **Concurrency:** Use Kotlin Coroutines and Flow. +- **Dependency Injection:** Use **Koin Annotations** with the K2 compiler plugin (0.4.0+). Keep root graph assembly in `app`. +- **ViewModels:** Follow the MVI/UDF pattern. Use the multiplatform `androidx.lifecycle.ViewModel` in `commonMain`. +- **BLE:** All Bluetooth communication must route through `core:ble` using Nordic Semiconductor's Android Common Libraries. +- **Dependencies:** Check `gradle/libs.versions.toml` before assuming a library is available. +- **Room KMP:** Always use `factory = { MeshtasticDatabaseConstructor.initialize() }` in `Room.databaseBuilder` and `inMemoryDatabaseBuilder`. DAOs and Entities reside in `commonMain`. +- **Testing:** Write ViewModel and business logic tests in `commonTest`. Use `core:testing` shared fakes. + +### C. Namespacing +- **Standard:** Use the `org.meshtastic.*` namespace for all code. +- **Legacy:** Maintain the `com.geeksville.mesh` Application ID. + +## 4. Execution Protocol + +### A. Environment Setup 1. **JDK 17 MUST be used** to prevent Gradle sync/build failures. -2. **Secrets:** You must copy `secrets.defaults.properties` to `local.properties` to satisfy build requirements, even for dummy builds: +2. **Secrets:** You must copy `secrets.defaults.properties` to `local.properties`: ```properties - # local.properties example MAPS_API_KEY=dummy_key datadogApplicationId=dummy_id datadogClientToken=dummy_token ``` -## 3. Strict Execution Commands +### B. Strict Execution Commands Always run commands in the following order to ensure reliability. Do not attempt to bypass `clean` if you are facing build issues. **Baseline (recommended order):** @@ -47,19 +105,6 @@ Always run commands in the following order to ensure reliability. Do not attempt ./gradlew test ``` -**Formatting & Linting (Run BEFORE committing):** -```bash -./gradlew spotlessCheck # Check formatting first -./gradlew spotlessApply # Auto-fix formatting -./gradlew detekt # Run static analysis -``` - -**Building:** -```bash -./gradlew clean # Always start here if facing issues -./gradlew assembleDebug # Full build (fdroid and google) -``` - **Testing:** ```bash ./gradlew test # Run local unit tests @@ -70,36 +115,12 @@ Always run commands in the following order to ensure reliability. Do not attempt ``` *Note: If testing Compose UI on the JVM (Robolectric) with Java 17, pin your tests to `@Config(sdk = [34])` to avoid SDK 35 compatibility crashes.* -## 4. Coding Standards & Mandates +### C. Documentation Sync +Update documentation continuously as part of the same change. If you modify architecture, module targets, CI tasks, validation commands, or agent workflow rules, update the relevant docs (`AGENTS.md`, `.github/copilot-instructions.md`, `GEMINI.md`, `docs/agent-playbooks/*`, `docs/kmp-status.md`, and `docs/decisions/architecture-review-2026-03.md`). -- **UI Components:** Always utilize `:core:ui` for shared Jetpack Compose components (e.g., `MeshtasticResourceDialog`, `TransportIcon`). Do not reinvent standard dialogs or preference screens. -- **Strings/Localization:** **NEVER** use hardcoded strings or the legacy `app/src/main/res/values/strings.xml`. - - **Rule:** You MUST use the Compose Multiplatform Resource library. - - **Location:** `core/resources/src/commonMain/composeResources/values/strings.xml`. - - **Usage:** `stringResource(Res.string.your_key)` -- **Platform purity:** Never import `java.*` or `android.*` in `commonMain`. Use KMP alternatives: - - `java.util.Locale` → Kotlin `uppercase()` / `lowercase()` (locale-independent for ASCII) or `expect`/`actual`. - - `java.util.concurrent.ConcurrentHashMap` → `atomicfu` or `Mutex`-guarded `mutableMapOf()`. - - `java.util.concurrent.locks.*` → `kotlinx.coroutines.sync.Mutex`. - - `java.io.*` → Okio (`BufferedSource`/`BufferedSink`). -- **Bluetooth/BLE:** Do not use legacy Android Bluetooth callbacks. All BLE communication MUST route through `:core:ble`, utilizing Nordic Semiconductor's Android Common Libraries and Kotlin Coroutines/Flows. -- **Dependencies:** Never assume a library is available. Check `gradle/libs.versions.toml` first. If adding a new dependency, it MUST be added to the version catalog, not directly to a `build.gradle.kts` file. -- **Namespacing:** Prefer the `org.meshtastic` namespace for all new code. The legacy `com.geeksville.mesh` ApplicationId is maintained for compatibility. -- **Testing:** Write ViewModel and business logic tests in `commonTest` (not `test/` Robolectric) so every target runs them. Use `core:testing` shared fakes when available. -- **Documentation Sync:** Update documentation continuously as part of the same change. If you modify architecture, module targets, CI tasks, validation commands, or agent workflow rules, update the relevant docs (`AGENTS.md`, `.github/copilot-instructions.md`, `GEMINI.md`, `docs/agent-playbooks/*`, `docs/kmp-status.md`, and `docs/decisions/architecture-review-2026-03.md`) in the same slice. - -## 5. Module Map -When locating code to modify, use this map: -- **`app/`**: Main application wiring and Koin DI modules/wrappers (`@KoinViewModel`, `@Module`, `@KoinWorker`). Package: `org.meshtastic.app`. -- **`:core:data`**: Core business logic and managers. Package: `org.meshtastic.core.data`. -- **`:core:repository`**: Domain interfaces and common models. Package: `org.meshtastic.core.repository`. -- **`:core:ble`**: Coroutine-based Bluetooth logic (Nordic Semiconductor). Package: `org.meshtastic.core.ble`. -- **`:core:nfc`**: NFC abstractions (KMP). Android NFC hardware in `androidMain`; shared contract via `LocalNfcScannerProvider` in `core:ui`. -- **`:core:barcode`**: Barcode scanning (Android-only). Shared UI in `main/`; only the decoder (`createBarcodeAnalyzer`) differs per flavor (ML Kit / ZXing). Shared contract in `core:ui`. -- **`:core:api`**: AIDL service interface (`IMeshService.aidl`) for third-party integrations (like ATAK). -- **`:core:ui`**: Shared Compose UI elements, platform abstractions, and theming. -- **`:core:navigation`**: Shared Navigation 3 routes/keys. -- **`:core:network`**: KMP networking (Ktor, `StreamFrameCodec`, `TcpTransport`). -- **`:core:testing`**: Shared test doubles, fakes, and utilities for `commonTest` across all KMP modules. -- **`:desktop`**: Compose Desktop application — first non-Android KMP target. Nav 3 shell, full Koin DI, TCP transport with `want_config` handshake, adaptive list-detail screens for nodes/messaging, ~35 real settings screens, connections UI. See `docs/kmp-status.md`. -- **`:feature:*`**: Isolated feature screens (e.g., `:feature:messaging` for chat, `:feature:map` for mapping, `:feature:connections` for device discovery, `:feature:firmware` for updates). +## 5. Troubleshooting +- **Build Failures:** Check `gradle/libs.versions.toml` for dependency conflicts. +- **Missing Secrets:** Check `local.properties`. +- **JDK Version:** JDK 17 is required. +- **Configuration Cache:** Add `--no-configuration-cache` flag if cache-related issues persist. +- **Koin Injection Failures:** Verify the KMP component is included in `app` root module wiring (`AppKoinModule`). \ No newline at end of file diff --git a/conductor/archive/desktop_parity_20260311/index.md b/conductor/archive/desktop_parity_20260311/index.md new file mode 100644 index 000000000..c034c2f20 --- /dev/null +++ b/conductor/archive/desktop_parity_20260311/index.md @@ -0,0 +1,5 @@ +# Track desktop_parity_20260311 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) \ No newline at end of file diff --git a/conductor/archive/desktop_parity_20260311/metadata.json b/conductor/archive/desktop_parity_20260311/metadata.json new file mode 100644 index 000000000..1eda225dc --- /dev/null +++ b/conductor/archive/desktop_parity_20260311/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "desktop_parity_20260311", + "type": "feature", + "status": "new", + "created_at": "2026-03-11T12:00:00Z", + "updated_at": "2026-03-11T12:00:00Z", + "description": "continue bringing desktop up to parity with android" +} \ No newline at end of file diff --git a/conductor/archive/desktop_parity_20260311/plan.md b/conductor/archive/desktop_parity_20260311/plan.md new file mode 100644 index 000000000..381d89d92 --- /dev/null +++ b/conductor/archive/desktop_parity_20260311/plan.md @@ -0,0 +1,41 @@ +# Implementation Plan + +## Phase 1: Navigation Parity [checkpoint: 5b8e194] +- [x] Task: Extract shared navigation contracts f7e0c2e + - [x] Define shared top-level destinations and route metadata in `core:navigation`. + - [x] Update Android `TopLevelDestination` to use the shared contract. + - [x] Update Desktop `DesktopDestination` to use the shared contract. + - [x] Add parity tests for navigation routing. +- [x] Task: Conductor - User Manual Verification 'Phase 1: Navigation Parity' (Protocol in workflow.md) + +## Phase 2: DI Parity [checkpoint: 5bdc099] +- [x] Task: Migrate Desktop Koin Modules 93fd600 + - [x] Configure KSP for the JVM target in necessary modules. + - [x] Ensure Koin annotations are processed for Desktop. + - [x] Replace manual ViewModel wiring in `DesktopKoinModule` with generated modules. +- [x] Task: Conductor - User Manual Verification 'Phase 2: DI Parity' (Protocol in workflow.md) + +## Phase 3: Connections Parity [checkpoint: 4be5732] +- [x] Task: Create `feature:connections` module 242faa6 + - [x] Set up the KMP module structure with `commonMain`, `androidMain`, and `jvmMain` (or `desktopMain`). + - [x] Move device discovery UI and ViewModels from `app` and `desktop` into the new module. + - [x] Consolidate the Connections UI into a shared screen in `feature:connections`. +- [x] Task: Conductor - User Manual Verification 'Phase 3: Connections Parity' (Protocol in workflow.md) + +## Phase 4: UI/Feature Parity [checkpoint: e83a07a] +- [x] Task: Implement missing Map and Chart features on Desktop 128ee3b + - [x] Evaluate and implement a KMP-friendly mapping library or placeholder for Desktop. + - [x] Refactor Vico charts or provide a KMP charting alternative/placeholder for Desktop. +- [x] Task: Refinement - Connections UI and Messaging Parity c98db4f + - [x] Hide unsupported transports (BLE/USB) on Desktop via BuildUtils proxy. + - [x] Update message titles to resolve channel names for broadcasts. + - [x] Add snackbar for no-op gaps (delivery info). + - [x] Shared AnimatedConnectionsNavIcon for "blinky light" parity. + - *Note: Connection type filtering is currently hardcoded via BuildUtils.sdkInt. This should be refactored to use dynamic transport discovery once the 'Extract hardware transport' track is complete.* +- [x] Task: Conductor - User Manual Verification 'Phase 4: UI/Feature Parity' (Protocol in workflow.md) e83a07a + +## Phase 5: Multi-Target Hardening [checkpoint: 91784a9] +- [x] Task: Clean up remaining platform-specific leaks f5f1e29 + - [x] Ensure `commonMain` is free of any `java.*` dependencies. + - [x] Verify test suite passes on both Android and Desktop JVM targets. +- [x] Task: Conductor - User Manual Verification 'Phase 5: Multi-Target Hardening' (Protocol in workflow.md) 91784a9 \ No newline at end of file diff --git a/conductor/archive/desktop_parity_20260311/spec.md b/conductor/archive/desktop_parity_20260311/spec.md new file mode 100644 index 000000000..27fef2b6f --- /dev/null +++ b/conductor/archive/desktop_parity_20260311/spec.md @@ -0,0 +1,25 @@ +# Track Specification: Desktop Parity & Multi-Target Hardening + +## Overview +This track aims to bring the Desktop target up to parity with the Android app and lay the foundation for future targets (like iOS). This involves eliminating duplicated code, fixing structural gaps, and sharing UI, navigation, and DI contracts across platforms. + +## Functional Requirements +- **Connections Parity:** Consolidate device discovery (BLE/USB/TCP) from the app and desktop into a shared `feature:connections` module. +- **DI Parity:** Remove manual ViewModel wiring in `DesktopKoinModule` and transition to using KSP-generated Koin modules for Desktop. +- **UI/Feature Parity:** Implement missing map and charting functionality on Desktop, or provide robust KMP abstractions where direct translation isn't possible. +- **Navigation Parity:** Extract shared navigation contracts to stop drift between Android and Desktop shells (following `decisions/navigation3-parity-2026-03.md`). + +## Non-Functional Requirements +- **Architecture Readiness:** Ensure code abstractions support the subsequent addition of an iOS target. +- **Structural Purity:** `commonMain` must be completely free of platform-specific APIs (like `java.*` or Android-specific APIs). + +## Acceptance Criteria +- Device discovery screens share UI and view models in `feature:connections`. +- Desktop DI uses generated modules without manual ViewModel instantiation. +- Map and charting features are either functioning on Desktop or have solid KMP placeholders. +- Android and Desktop Navigation shells utilize shared configuration and metadata. +- Both functional and structural parity goals are verified through automated builds and testing where applicable. + +## Out of Scope +- Full deployment to iOS or other unannounced platforms (only preparing the architecture). +- Deep refactoring of underlying hardware interactions beyond what is necessary to expose a shared UI contract. \ No newline at end of file diff --git a/conductor/archive/doc_consolidation_20260311/index.md b/conductor/archive/doc_consolidation_20260311/index.md new file mode 100644 index 000000000..0ed0c002c --- /dev/null +++ b/conductor/archive/doc_consolidation_20260311/index.md @@ -0,0 +1,5 @@ +# Track doc_consolidation_20260311 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) \ No newline at end of file diff --git a/conductor/archive/doc_consolidation_20260311/metadata.json b/conductor/archive/doc_consolidation_20260311/metadata.json new file mode 100644 index 000000000..97337ceaf --- /dev/null +++ b/conductor/archive/doc_consolidation_20260311/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "doc_consolidation_20260311", + "type": "feature", + "status": "new", + "created_at": "2026-03-11T00:00:00Z", + "updated_at": "2026-03-11T00:00:00Z", + "description": "Implement document consolidation plan" +} \ No newline at end of file diff --git a/conductor/archive/doc_consolidation_20260311/plan.md b/conductor/archive/doc_consolidation_20260311/plan.md new file mode 100644 index 000000000..692ebe8be --- /dev/null +++ b/conductor/archive/doc_consolidation_20260311/plan.md @@ -0,0 +1,35 @@ +# Implementation Plan: Implement document consolidation plan + +## Phase 1: Prune and Consolidate Session Artifacts +- [x] Task: Consolidate session artifacts into `docs/archive/kmp-phase3-testing-consolidation.md`. [d8becb2] + - [x] Write Tests (Verify documentation structure) + - [x] Read all 12+ session update files. + - [x] Create `kmp-phase3-testing-consolidation.md` with merged key findings and test coverage metrics. +- [x] Task: Delete redundant point-in-time files from `docs/agent-playbooks/`. [d8becb2] + - [x] Write Tests (Verify file removal) + - [x] Delete `CHECKLIST-testing-consolidation.md` and other 11 listed files. +- [x] Task: Relocate remaining planning documents. [d8becb2] + - [x] Write Tests (Verify correct destination paths) + - [x] Merge `phase-4-desktop-completion-plan.md` into `docs/roadmap.md` under Phase 4 Desktop section and delete the original. + - [x] Move `kmp-feature-migration-plan.md` to `docs/archive/`. +- [x] Task: Conductor - User Manual Verification 'Phase 1: Prune and Consolidate Session Artifacts' (Protocol in workflow.md) [checkpoint: d8becb2] + +## Phase 2: Synthesize Status & Roadmap +- [x] Task: Update `docs/kmp-status.md`. [37fd055] + - [x] Write Tests (Verify updated metric output) + - [x] Update testing score to reflect Phase 3 completion (80 tests across 6 features). +- [x] Task: Update `docs/roadmap.md`. [37fd055] + - [x] Write Tests (Verify roadmap section exists) + - [x] Mark Phase 3 as substantially complete. +- [x] Task: Conductor - User Manual Verification 'Phase 2: Synthesize Status & Roadmap' (Protocol in workflow.md) [checkpoint: 37fd055] + +## Phase 3: Verify and Validate Best Practices +- [x] Task: Update `AGENTS.md` and playbooks for 2026 KMP Best Practices. [85db394] + - [x] Write Tests (Verify updated content) + - [x] Document Koin Annotations (K2) best practices in `AGENTS.md` and `di-navigation3-anti-patterns-playbook.md`. + - [x] Document Shared ViewModels (MVI) recommendations. +- [x] Task: Documentation Quality Checks. [85db394] + - [x] Write Tests (Verify links resolve) + - [x] Update `docs/agent-playbooks/README.md`. + - [x] Rename `testing-quick-ref.sh` to `testing-quick-ref.md` and update internal references. +- [x] Task: Conductor - User Manual Verification 'Phase 3: Verify and Validate Best Practices' (Protocol in workflow.md) [checkpoint: 85db394] \ No newline at end of file diff --git a/conductor/archive/doc_consolidation_20260311/spec.md b/conductor/archive/doc_consolidation_20260311/spec.md new file mode 100644 index 000000000..3f4e512c6 --- /dev/null +++ b/conductor/archive/doc_consolidation_20260311/spec.md @@ -0,0 +1,13 @@ +# Track Specification: Implement document consolidation plan + +## Objective +Consolidate, prune, verify, and validate project plans and documentation against 2026 Kotlin Multiplatform (KMP) best practices and the latest dependency standards. + +## Background & Motivation +The `docs/agent-playbooks/` directory has accumulated numerous point-in-time session summaries, checklists, and status reports (e.g., `SESSION-FINAL-SUMMARY.md`, `TEST-VERIFICATION-REPORT.md`) during the Phase 3 testing consolidation sprint. These files clutter the directory and dilute the actual "playbooks" (reusable guides). Additionally, the project documentation (`kmp-status.md`, `roadmap.md`, `AGENTS.md`) needs to be synthesized to reflect the recently completed work and validated against 2026 KMP industry standards (e.g., Koin K2 compiler plugin best practices, shared ViewModels, Navigation 3). + +## Scope +1. **Prune and Consolidate Session Artifacts:** Merge the key findings into a single historical record (`docs/archive/kmp-phase3-testing-consolidation.md`) and delete 12+ redundant point-in-time files. Relocate `phase-4-desktop-completion-plan.md` into `docs/roadmap.md` and move `kmp-feature-migration-plan.md` to `docs/archive/`. +2. **Synthesize Status & Roadmap:** Update `docs/kmp-status.md` and `docs/roadmap.md` with new testing metrics (80 tests across 6 features) and expanded Phase 4 Desktop tasks. +3. **Verify and Validate against 2026 KMP Best Practices:** Validate the usage of Koin `@Module` and `@KoinViewModel` annotations in `commonMain` according to Koin 4.2 native compiler plugin best practices. Update `AGENTS.md` and `di-navigation3-anti-patterns-playbook.md` to officially recommend this pattern and multiplatform `androidx.lifecycle.ViewModel` in `commonMain`. +4. **Documentation Quality Checks:** Verify `README.md` in playbooks correctly points to retained playbooks. Rename `testing-quick-ref.sh` to `testing-quick-ref.md` and update internal references. \ No newline at end of file diff --git a/conductor/archive/extract_hardware_transport_20260311/index.md b/conductor/archive/extract_hardware_transport_20260311/index.md new file mode 100644 index 000000000..0c9c915e4 --- /dev/null +++ b/conductor/archive/extract_hardware_transport_20260311/index.md @@ -0,0 +1,5 @@ +# Track extract_hardware_transport_20260311 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) \ No newline at end of file diff --git a/conductor/archive/extract_hardware_transport_20260311/metadata.json b/conductor/archive/extract_hardware_transport_20260311/metadata.json new file mode 100644 index 000000000..2d9cc643e --- /dev/null +++ b/conductor/archive/extract_hardware_transport_20260311/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "extract_hardware_transport_20260311", + "type": "feature", + "status": "new", + "created_at": "2026-03-11T00:00:00Z", + "updated_at": "2026-03-11T00:00:00Z", + "description": "extract hardware/transport layers out of :app into dedicated :core modules" +} \ No newline at end of file diff --git a/conductor/archive/extract_hardware_transport_20260311/plan.md b/conductor/archive/extract_hardware_transport_20260311/plan.md new file mode 100644 index 000000000..87b43b632 --- /dev/null +++ b/conductor/archive/extract_hardware_transport_20260311/plan.md @@ -0,0 +1,37 @@ +# Implementation Plan: Extract hardware/transport layers out of :app into dedicated :core modules + +## Phase 1: Define Shared Interface and Extract Stream Framing [checkpoint: 80a39a5] +- [x] Task: Create `RadioTransport` interface in `core:repository/commonMain`. a47f399 + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Move `StreamFrameCodec` logic to `core:network/commonMain`. cc1ff26 + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Refactor existing `IRadioInterface` usages to point to the new `RadioTransport` interface (preparation step). 1b4cec6 + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Conductor - User Manual Verification 'Phase 1: Define Shared Interface and Extract Stream Framing' (Protocol in workflow.md) 80a39a5 + +## Phase 2: Extract Platform Transports +- [x] Task: Move TCP transport implementation to `core:network/jvmAndroidMain`. [8688070] + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Move BLE transport implementation to `core:ble/androidMain`. [8688070] + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Move Serial/USB transport implementation to `core:service/androidMain`. [8688070] + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Conductor - User Manual Verification 'Phase 2: Extract Platform Transports' (Protocol in workflow.md) [checkpoint: 8688070] + +## Phase 3: Desktop Unification and Cleanup +- [x] Task: Retire `DesktopRadioInterfaceService` in the `desktop` module. + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Update the `desktop` DI graph to inject the shared `TcpTransport` implementation. + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Delete the old `app/repository/radio/` directory. + - [x] Write Tests + - [x] Implement Feature +- [x] Task: Conductor - User Manual Verification 'Phase 3: Desktop Unification and Cleanup' (Protocol in workflow.md) [checkpoint: 8688070] \ No newline at end of file diff --git a/conductor/archive/extract_hardware_transport_20260311/spec.md b/conductor/archive/extract_hardware_transport_20260311/spec.md new file mode 100644 index 000000000..0a52436a9 --- /dev/null +++ b/conductor/archive/extract_hardware_transport_20260311/spec.md @@ -0,0 +1,22 @@ +# Track Specification: Extract hardware/transport layers out of :app into dedicated :core modules + +## Overview +This track addresses a critical modularity gap identified in the KMP architecture review: the Radio interface layer is currently locked within the `app` module and is non-KMP. The goal is to define a shared `RadioTransport` interface in `core:repository` and fully extract all transport implementations (BLE, TCP, USB) from `app/repository/radio/` into their appropriate `core` modules. + +## Functional Requirements +- **Define `RadioTransport` Interface:** Create a new `RadioTransport` interface in `core:repository/commonMain` to replace the existing `IRadioInterface`. +- **Extract Stream Framing:** Move `StreamFrameCodec`-based framing logic to `core:network/commonMain`. +- **Extract BLE Transport:** Move the BLE transport implementation (`NordicBleInterface`, etc.) to `core:ble/androidMain`. +- **Extract TCP Transport:** Move the TCP transport implementation to `core:network/jvmAndroidMain`. +- **Extract Serial/USB Transport:** Move the Serial/USB transport implementation to `core:service/androidMain`. +- **Unify Desktop Transport:** Retire Desktop's parallel `DesktopRadioInterfaceService` and migrate it to use the shared `RadioTransport` and `TcpTransport`. + +## Acceptance Criteria +- [ ] A `RadioTransport` interface exists in `core:repository/commonMain`. +- [ ] No transport logic (BLE, TCP, USB) remains in `app/repository/radio/`. +- [ ] The `app` and `desktop` modules successfully compile and run using the extracted transport layers. +- [ ] The `desktop` module uses the shared `TcpTransport` implementation instead of its own duplicate logic. + +## Out of Scope +- Rewriting the underlying logic of the transports (e.g., changing how Nordic BLE works). This is purely a structural extraction and KMP alignment. +- Extracting non-transport components (like the Connections UI) from the `app` module. \ No newline at end of file diff --git a/conductor/archive/kmp_doc_review_20260313/index.md b/conductor/archive/kmp_doc_review_20260313/index.md new file mode 100644 index 000000000..a503dd5bd --- /dev/null +++ b/conductor/archive/kmp_doc_review_20260313/index.md @@ -0,0 +1,5 @@ +# Track kmp_doc_review_20260313 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) \ No newline at end of file diff --git a/conductor/archive/kmp_doc_review_20260313/metadata.json b/conductor/archive/kmp_doc_review_20260313/metadata.json new file mode 100644 index 000000000..fcd5405ec --- /dev/null +++ b/conductor/archive/kmp_doc_review_20260313/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "kmp_doc_review_20260313", + "type": "chore", + "status": "new", + "created_at": "2026-03-13T12:00:00Z", + "updated_at": "2026-03-13T12:00:00Z", + "description": "do a thorough review of the project docs for quality and veracity against the current codebase and recent changes - use tooling as needed. Evaluate updating project documentation for clarity and context. Synthesize and condense documentation and plans as needed. Be sure to thoroughly investigate the current state of the codebase and it's migration to kmp." +} \ No newline at end of file diff --git a/conductor/archive/kmp_doc_review_20260313/plan.md b/conductor/archive/kmp_doc_review_20260313/plan.md new file mode 100644 index 000000000..87f83f8d1 --- /dev/null +++ b/conductor/archive/kmp_doc_review_20260313/plan.md @@ -0,0 +1,23 @@ +# Implementation Plan + +## Phase 1: Context Gathering and Codebase Investigation [checkpoint: b644b50] +- [x] Task: Investigate current state of KMP migration [42c36f0] + - [x] Run tooling to analyze KMP modules (`core:*`) vs Android-only modules. + - [x] Identify discrepancies between actual code structure and current documentation. +- [x] Task: Review existing documentation [d87b7a2] + - [x] Review Conductor strategy docs (`conductor/`). + - [x] Review Root docs (`README.md`, `AGENTS.md`, `GEMINI.md`). + - [x] Review `docs/` directory contents. +- [x] Task: Conductor - User Manual Verification 'Context Gathering and Codebase Investigation' (Protocol in workflow.md) [b644b50] + +## Phase 2: Synthesis and Condensation [checkpoint: 40e7c58] +- [x] Task: Synthesize documentation [8c57f14] + - [x] Consolidate related guides into single sources of truth. + - [x] Update documentation to reflect recent KMP migration findings. +- [x] Task: Archive legacy documentation [14b19c5] + - [x] Identify outdated or redundant documents. + - [x] Move identified documents into an `archive/` directory. +- [x] Task: Formulate next steps proposal [2bd7655] + - [x] Draft a proposed plan for remaining KMP migrations based on investigation. + - [x] Document the proposal in the relevant file (e.g., `kmp-status.md`). +- [x] Task: Conductor - User Manual Verification 'Synthesis and Condensation' (Protocol in workflow.md) [40e7c58] \ No newline at end of file diff --git a/conductor/archive/kmp_doc_review_20260313/spec.md b/conductor/archive/kmp_doc_review_20260313/spec.md new file mode 100644 index 000000000..a15e676d0 --- /dev/null +++ b/conductor/archive/kmp_doc_review_20260313/spec.md @@ -0,0 +1,24 @@ +# Overview +This track involves a thorough review, synthesis, and condensation of the project's documentation for quality and veracity against the current codebase and recent changes. It includes a deep investigation into the current state of the codebase, specifically focusing on its migration to Kotlin Multiplatform (KMP). + +# Functional Requirements +- Conduct a comprehensive review of Conductor strategy docs (`conductor/`), Root repository docs (e.g., `README.md`, `AGENTS.md`), the `docs/` directory, and inline source code docstrings. +- Investigate the current state of KMP migration across the codebase. +- Synthesize and condense existing documentation into clarified, updated guides. +- Archive old, redundant, or outdated documentation. +- Formulate a proposed plan and next steps for the remaining KMP migrations. + +# Non-Functional Requirements +- Ensure documentation is accurate, clear, and contextually aligned with recent codebase changes. +- Use appropriate tooling to analyze the codebase and verify documentation claims. + +# Acceptance Criteria +- [ ] A consolidated, up-to-date documentation structure exists. +- [ ] Legacy or redundant documents are moved to an archive folder. +- [ ] An accurate report of the current KMP migration status is produced. +- [ ] A proposal for the next steps in the KMP migration is documented. +- [ ] Conductor docs, Root docs, the `docs/` directory, and key docstrings align with the actual codebase implementation. + +# Out of Scope +- Actually executing the proposed KMP migrations (this track is purely documentation and planning). +- Modifying application business logic or UI code. \ No newline at end of file diff --git a/conductor/code_styleguides/general.md b/conductor/code_styleguides/general.md new file mode 100644 index 000000000..dfcc793f4 --- /dev/null +++ b/conductor/code_styleguides/general.md @@ -0,0 +1,23 @@ +# General Code Style Principles + +This document outlines general coding principles that apply across all languages and frameworks used in this project. + +## Readability +- Code should be easy to read and understand by humans. +- Avoid overly clever or obscure constructs. + +## Consistency +- Follow existing patterns in the codebase. +- Maintain consistent formatting, naming, and structure. + +## Simplicity +- Prefer simple solutions over complex ones. +- Break down complex problems into smaller, manageable parts. + +## Maintainability +- Write code that is easy to modify and extend. +- Minimize dependencies and coupling. + +## Documentation +- Document *why* something is done, not just *what*. +- Keep documentation up-to-date with code changes. diff --git a/conductor/doc-consolidation-plan.md b/conductor/doc-consolidation-plan.md new file mode 100644 index 000000000..1ce4cfe07 --- /dev/null +++ b/conductor/doc-consolidation-plan.md @@ -0,0 +1,53 @@ +# Objective +Consolidate, prune, verify, and validate project plans and documentation against 2026 Kotlin Multiplatform (KMP) best practices and the latest dependency standards. + +# Background & Motivation +The `docs/agent-playbooks/` directory has accumulated numerous point-in-time session summaries, checklists, and status reports (e.g., `SESSION-FINAL-SUMMARY.md`, `TEST-VERIFICATION-REPORT.md`) during the Phase 3 testing consolidation sprint. These files clutter the directory and dilute the actual "playbooks" (reusable guides). Additionally, the project documentation (`kmp-status.md`, `roadmap.md`, `AGENTS.md`) needs to be synthesized to reflect the recently completed work and validated against 2026 KMP industry standards (e.g., Koin K2 compiler plugin best practices, shared ViewModels, Navigation 3). + +# Proposed Solution + +## 1. Prune and Consolidate Session Artifacts +- **Consolidate:** Merge the key findings, test coverage metrics (80 tests across 6 features), and testing patterns from the 12+ session update files into a single historical record: `docs/archive/kmp-phase3-testing-consolidation.md`. +- **Prune:** Delete the following redundant point-in-time files from `docs/agent-playbooks/`: + - `CHECKLIST-testing-consolidation.md` + - `FINAL-STATUS-tests-fixed.md` + - `MIGRATION-COMPLETE-SUMMARY.md` + - `SESSION-FINAL-SUMMARY.md` + - `SESSION-STATUS-2026-03-11.md` + - `TEST-VERIFICATION-REPORT.md` + - `fix-core-domain-tests.md` + - `kmp-testing-consolidation-slice.md` + - `phase-1-feature-commontest-bootstrap.md` + - `phase-3-completion.md` + - `phase-3-implementation-plan.md` + - `phase-3-integration-tests-started.md` +- **Relocate:** + - Extract the contents of `phase-4-desktop-completion-plan.md` and merge them into `docs/roadmap.md` under the Phase 4 Desktop section. Delete the original file. + - Move `kmp-feature-migration-plan.md` to `docs/archive/` since Phase 3 is mostly complete. + +## 2. Synthesize Status & Roadmap +- **Update `docs/kmp-status.md`:** Update the testing score (currently 5/10) to reflect the completion of Phase 3 integration testing (80 tests across 6 features, test doubles in `core:testing`). +- **Update `docs/roadmap.md`:** Mark Phase 3 as substantially complete. Expand the Phase 4 (Desktop Feature Completion) section using the consolidated plan details. + +## 3. Verify and Validate against 2026 KMP Best Practices +Based on a review of 2026 KMP standards and the project's current dependencies (`Koin 4.2.0-RC1`, `Compose Multiplatform 1.11.0-alpha03`, `Navigation 3 1.1.0-alpha03`): +- **Koin Annotations (K2):** The project's decision to move Koin `@Module` and `@KoinViewModel` annotations into `commonMain` aligns perfectly with Koin 4.2 native compiler plugin best practices. The documentation (`AGENTS.md`, `docs/decisions/architecture-review-2026-03.md`) will be validated and explicitly updated to affirm that this is the correct architectural pattern, not a "portability tradeoff". +- **Shared ViewModels (MVI):** Ensure playbook documentation explicitly recommends utilizing the multiplatform `androidx.lifecycle.ViewModel` in `commonMain` to maintain a single source of truth, heavily relying on `StateFlow`. +- **Navigation 3:** The hybrid parity strategy (shared route contracts, platform adapters) is validated as the 2026 standard for Compose Multiplatform. + +## 4. Documentation Quality Checks +- Verify `docs/agent-playbooks/README.md` correctly points only to the retained playbooks. +- Rename `testing-quick-ref.sh` to `testing-quick-ref.md` for proper markdown rendering and update internal references. + +# Implementation Steps +1. Create `docs/archive/kmp-phase3-testing-consolidation.md` and synthesize the 12+ session artifacts into it. +2. Delete the 12+ redundant session files from `docs/agent-playbooks/`. +3. Update `docs/kmp-status.md` and `docs/roadmap.md` with the new testing metrics and Phase 4 desktop tasks. +4. Rename `testing-quick-ref.sh` to `testing-quick-ref.md` and update internal references. +5. Update `docs/agent-playbooks/README.md` to reflect the pruned directory. +6. Refine `AGENTS.md` and `docs/agent-playbooks/di-navigation3-anti-patterns-playbook.md` to validate Koin K2 multiplatform annotations as the officially recommended pattern. + +# Verification & Testing +- Run `ls docs/agent-playbooks/` to ensure only high-signal playbooks remain. +- Ensure `docs/kmp-status.md` reflects an updated test maturity score (e.g., 8/10). +- Run `git status` and `git diff` to ensure changes are accurate. \ No newline at end of file diff --git a/conductor/index.md b/conductor/index.md new file mode 100644 index 000000000..3a362bc99 --- /dev/null +++ b/conductor/index.md @@ -0,0 +1,14 @@ +# Project Context + +## Definition +- [Product Definition](./product.md) +- [Product Guidelines](./product-guidelines.md) +- [Tech Stack](./tech-stack.md) + +## Workflow +- [Workflow](./workflow.md) +- [Code Style Guides](./code_styleguides/) + +## Management +- [Tracks Registry](./tracks.md) +- [Tracks Directory](./tracks/) \ No newline at end of file diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md new file mode 100644 index 000000000..b54944fea --- /dev/null +++ b/conductor/product-guidelines.md @@ -0,0 +1,19 @@ +# Product Guidelines + +## Brand Voice and Tone +- **Technical yet Accessible:** Communicate complex networking and hardware concepts clearly without being overly academic. +- **Reliable and Authoritative:** The app is a utility for critical, off-grid communication. Language should convey stability and safety. +- **Community-Oriented:** Encourage open-source participation and community support. + +## UX Principles +- **Offline-First:** Assume the user has no cellular or Wi-Fi connection. All core functions must work locally via the mesh network. +- **Adaptive Layouts:** Support multiple form factors seamlessly (phones, tablets, desktop) using Material 3 Adaptive Scaffold principles. +- **Information Density:** Give power users access to detailed metrics (SNR, battery, hop limits) without overwhelming beginners. Use progressive disclosure. + +## Prose Style +- **Clarity over cleverness:** Use plain English. +- **Action-oriented:** Button labels and prompts should start with strong verbs (e.g., "Send", "Connect", "Export"). +- **Consistent Terminology:** + - Use "Node" for devices on the network. + - Use "Channel" for communication groups. + - Use "Direct Message" for 1-to-1 communication. \ No newline at end of file diff --git a/conductor/product.md b/conductor/product.md new file mode 100644 index 000000000..669ac7711 --- /dev/null +++ b/conductor/product.md @@ -0,0 +1,24 @@ +# Initial Concept +A tool for using Android with open-source mesh radios. + +# Product Guide + +## Overview +Meshtastic-Android is a Kotlin Multiplatform (KMP) application designed to facilitate communication over off-grid, decentralized mesh networks using open-source hardware radios. + +## Target Audience +- Off-grid communication enthusiasts and hobbyists +- Outdoor adventurers needing reliable communication without cellular networks +- Emergency response and disaster relief teams + +## Core Features +- Direct communication with Meshtastic hardware (via BLE, USB, TCP) +- Decentralized text messaging across the mesh network +- Adaptive node and contact management +- Offline map rendering and device positioning +- Device configuration and firmware updates + +## Key Architecture Goals +- Provide a robust, shared KMP core (`core:model`, `core:repository`, `core:domain`, `core:data`, `core:network`) to support multiple platforms (Android, Desktop, iOS) +- Ensure offline-first functionality and resilient data persistence (Room KMP) +- Decouple UI logic into shared components (`core:ui`, `feature:*`) using Compose Multiplatform \ No newline at end of file diff --git a/conductor/tech-stack.md b/conductor/tech-stack.md new file mode 100644 index 000000000..7ed80565f --- /dev/null +++ b/conductor/tech-stack.md @@ -0,0 +1,23 @@ +# Tech Stack + +## Programming Language +- **Kotlin Multiplatform (KMP):** The core logic is shared across Android, Desktop, and iOS using `commonMain`. + +## Frontend Frameworks +- **Compose Multiplatform:** Shared UI layer for rendering on Android and Desktop. +- **Jetpack Compose:** Used where platform-specific UI (like charts or permissions) is necessary on Android. + +## Architecture +- **MVI / Unidirectional Data Flow:** Shared view models using the multiplatform `androidx.lifecycle.ViewModel`. +- **JetBrains Navigation 3:** Multiplatform fork for state-based, compose-first navigation without relying on `NavController`. + +## Dependency Injection +- **Koin 4.2:** Leverages Koin Annotations and the K2 Compiler Plugin for pure compile-time DI, completely replacing Hilt. + +## Database & Storage +- **Room KMP:** Shared local database using multiplatform `DatabaseConstructor`. +- **Jetpack DataStore:** Shared preferences. + +## Networking & Transport +- **Ktor:** Multiplatform HTTP client for web services and TCP streaming. +- **Coroutines & Flows:** For asynchronous programming and state management. \ No newline at end of file diff --git a/conductor/tracks.md b/conductor/tracks.md new file mode 100644 index 000000000..b0b15a077 --- /dev/null +++ b/conductor/tracks.md @@ -0,0 +1,3 @@ +# Project Tracks + +This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder. \ No newline at end of file diff --git a/conductor/workflow.md b/conductor/workflow.md new file mode 100644 index 000000000..6f9cfd8fc --- /dev/null +++ b/conductor/workflow.md @@ -0,0 +1,333 @@ +# Project Workflow + +## Guiding Principles + +1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md` +2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation +3. **Test-Driven Development:** Write unit tests before implementing functionality +4. **High Code Coverage:** Aim for >80% code coverage for all modules +5. **User Experience First:** Every decision should prioritize user experience +6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution. + +## Task Workflow + +All tasks follow a strict lifecycle: + +### Standard Task Workflow + +1. **Select Task:** Choose the next available task from `plan.md` in sequential order + +2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]` + +3. **Write Failing Tests (Red Phase):** + - Create a new test file for the feature or bug fix. + - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task. + - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests. + +4. **Implement to Pass Tests (Green Phase):** + - Write the minimum amount of application code necessary to make the failing tests pass. + - Run the test suite again and confirm that all tests now pass. This is the "Green" phase. + +5. **Refactor (Optional but Recommended):** + - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior. + - Rerun tests to ensure they still pass after refactoring. + +6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like: + ```bash + pytest --cov=app --cov-report=html + ``` + Target: >80% coverage for new code. The specific tools and commands will vary by language and framework. + +7. **Document Deviations:** If implementation differs from tech stack: + - **STOP** implementation + - Update `tech-stack.md` with new design + - Add dated note explaining the change + - Resume implementation + +8. **Commit Code Changes:** + - Stage all code changes related to the task. + - Propose a clear, concise commit message e.g, `feat(ui): Create basic HTML structure for calculator`. + - Perform the commit. + +9. **Attach Task Summary with Git Notes:** + - **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`). + - **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change. + - **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit. + ```bash + # The note content from the previous step is passed via the -m flag. + git notes add -m "" + ``` + +10. **Get and Record Task Commit SHA:** + - **Step 10.1: Update Plan:** Read `plan.md`, find the line for the completed task, update its status from `[~]` to `[x]`, and append the first 7 characters of the *just-completed commit's* commit hash. + - **Step 10.2: Write Plan:** Write the updated content back to `plan.md`. + +11. **Commit Plan Update:** + - **Action:** Stage the modified `plan.md` file. + - **Action:** Commit this change with a descriptive message (e.g., `conductor(plan): Mark task 'Create user model' as complete`). + +### Phase Completion Verification and Checkpointing Protocol + +**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`. + +1. **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun. + +2. **Ensure Test Coverage for Phase Changes:** + - **Step 2.1: Determine Phase Scope:** To identify the files changed in this phase, you must first find the starting point. Read `plan.md` to find the Git commit SHA of the *previous* phase's checkpoint. If no previous checkpoint exists, the scope is all changes since the first commit. + - **Step 2.2: List Changed Files:** Execute `git diff --name-only HEAD` to get a precise list of all files modified during this phase. + - **Step 2.3: Verify and Create Tests:** For each file in the list: + - **CRITICAL:** First, check its extension. Exclude non-code files (e.g., `.json`, `.md`, `.yaml`). + - For each remaining code file, verify a corresponding test file exists. + - If a test file is missing, you **must** create one. Before writing the test, **first, analyze other test files in the repository to determine the correct naming convention and testing style.** The new tests **must** validate the functionality described in this phase's tasks (`plan.md`). + +3. **Execute Automated Tests with Proactive Debugging:** + - Before execution, you **must** announce the exact shell command you will use to run the tests. + - **Example Announcement:** "I will now run the automated test suite to verify the phase. **Command:** `CI=true npm test`" + - Execute the announced command. + - If tests fail, you **must** inform the user and begin debugging. You may attempt to propose a fix a **maximum of two times**. If the tests still fail after your second proposed fix, you **must stop**, report the persistent failure, and ask the user for guidance. + +4. **Propose a Detailed, Actionable Manual Verification Plan:** + - **CRITICAL:** To generate the plan, first analyze `product.md`, `product-guidelines.md`, and `plan.md` to determine the user-facing goals of the completed phase. + - You **must** generate a step-by-step plan that walks the user through the verification process, including any necessary commands and specific, expected outcomes. + - The plan you present to the user **must** follow this format: + + **For a Frontend Change:** + ``` + The automated tests have passed. For manual verification, please follow these steps: + + **Manual Verification Steps:** + 1. **Start the development server with the command:** `npm run dev` + 2. **Open your browser to:** `http://localhost:3000` + 3. **Confirm that you see:** The new user profile page, with the user's name and email displayed correctly. + ``` + + **For a Backend Change:** + ``` + The automated tests have passed. For manual verification, please follow these steps: + + **Manual Verification Steps:** + 1. **Ensure the server is running.** + 2. **Execute the following command in your terminal:** `curl -X POST http://localhost:8080/api/v1/users -d '{"name": "test"}'` + 3. **Confirm that you receive:** A JSON response with a status of `201 Created`. + ``` + +5. **Await Explicit User Feedback:** + - After presenting the detailed plan, ask the user for confirmation: "**Does this meet your expectations? Please confirm with yes or provide feedback on what needs to be changed.**" + - **PAUSE** and await the user's response. Do not proceed without an explicit yes or confirmation. + +6. **Create Checkpoint Commit:** + - Stage all changes. If no changes occurred in this step, proceed with an empty commit. + - Perform the commit with a clear and concise message (e.g., `conductor(checkpoint): Checkpoint end of Phase X`). + +7. **Attach Auditable Verification Report using Git Notes:** + - **Step 7.1: Draft Note Content:** Create a detailed verification report including the automated test command, the manual verification steps, and the user's confirmation. + - **Step 7.2: Attach Note:** Use the `git notes` command and the full commit hash from the previous step to attach the full report to the checkpoint commit. + +8. **Get and Record Phase Checkpoint SHA:** + - **Step 8.1: Get Commit Hash:** Obtain the hash of the *just-created checkpoint commit* (`git log -1 --format="%H"`). + - **Step 8.2: Update Plan:** Read `plan.md`, find the heading for the completed phase, and append the first 7 characters of the commit hash in the format `[checkpoint: ]`. + - **Step 8.3: Write Plan:** Write the updated content back to `plan.md`. + +9. **Commit Plan Update:** + - **Action:** Stage the modified `plan.md` file. + - **Action:** Commit this change with a descriptive message following the format `conductor(plan): Mark phase '' as complete`. + +10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created, with the detailed verification report attached as a git note. + +### Quality Gates + +Before marking any task complete, verify: + +- [ ] All tests pass +- [ ] Code coverage meets requirements (>80%) +- [ ] Code follows project's code style guidelines (as defined in `code_styleguides/`) +- [ ] All public functions/methods are documented (e.g., docstrings, JSDoc, GoDoc) +- [ ] Type safety is enforced (e.g., type hints, TypeScript types, Go types) +- [ ] No linting or static analysis errors (using the project's configured tools) +- [ ] Works correctly on mobile (if applicable) +- [ ] Documentation updated if needed +- [ ] No security vulnerabilities introduced + +## Development Commands + +**AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.** + +### Setup +```bash +# Example: Commands to set up the development environment (e.g., install dependencies, configure database) +# e.g., for a Node.js project: npm install +# e.g., for a Go project: go mod tidy +``` + +### Daily Development +```bash +# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format) +# e.g., for a Node.js project: npm run dev, npm test, npm run lint +# e.g., for a Go project: go run main.go, go test ./..., go fmt ./... +``` + +### Before Committing +```bash +# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests) +# e.g., for a Node.js project: npm run check +# e.g., for a Go project: make check (if a Makefile exists) +``` + +## Testing Requirements + +### Unit Testing +- Every module must have corresponding tests. +- Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach). +- Mock external dependencies. +- Test both success and failure cases. + +### Integration Testing +- Test complete user flows +- Verify database transactions +- Test authentication and authorization +- Check form submissions + +### Mobile Testing +- Test on actual iPhone when possible +- Use Safari developer tools +- Test touch interactions +- Verify responsive layouts +- Check performance on 3G/4G + +## Code Review Process + +### Self-Review Checklist +Before requesting review: + +1. **Functionality** + - Feature works as specified + - Edge cases handled + - Error messages are user-friendly + +2. **Code Quality** + - Follows style guide + - DRY principle applied + - Clear variable/function names + - Appropriate comments + +3. **Testing** + - Unit tests comprehensive + - Integration tests pass + - Coverage adequate (>80%) + +4. **Security** + - No hardcoded secrets + - Input validation present + - SQL injection prevented + - XSS protection in place + +5. **Performance** + - Database queries optimized + - Images optimized + - Caching implemented where needed + +6. **Mobile Experience** + - Touch targets adequate (44x44px) + - Text readable without zooming + - Performance acceptable on mobile + - Interactions feel native + +## Commit Guidelines + +### Message Format +``` +(): + +[optional body] + +[optional footer] +``` + +### Types +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation only +- `style`: Formatting, missing semicolons, etc. +- `refactor`: Code change that neither fixes a bug nor adds a feature +- `test`: Adding missing tests +- `chore`: Maintenance tasks + +### Examples +```bash +git commit -m "feat(auth): Add remember me functionality" +git commit -m "fix(posts): Correct excerpt generation for short posts" +git commit -m "test(comments): Add tests for emoji reaction limits" +git commit -m "style(mobile): Improve button touch targets" +``` + +## Definition of Done + +A task is complete when: + +1. All code implemented to specification +2. Unit tests written and passing +3. Code coverage meets project requirements +4. Documentation complete (if applicable) +5. Code passes all configured linting and static analysis checks +6. Works beautifully on mobile (if applicable) +7. Implementation notes added to `plan.md` +8. Changes committed with proper message +9. Git note with task summary attached to the commit + +## Emergency Procedures + +### Critical Bug in Production +1. Create hotfix branch from main +2. Write failing test for bug +3. Implement minimal fix +4. Test thoroughly including mobile +5. Deploy immediately +6. Document in plan.md + +### Data Loss +1. Stop all write operations +2. Restore from latest backup +3. Verify data integrity +4. Document incident +5. Update backup procedures + +### Security Breach +1. Rotate all secrets immediately +2. Review access logs +3. Patch vulnerability +4. Notify affected users (if any) +5. Document and update security procedures + +## Deployment Workflow + +### Pre-Deployment Checklist +- [ ] All tests passing +- [ ] Coverage >80% +- [ ] No linting errors +- [ ] Mobile testing complete +- [ ] Environment variables configured +- [ ] Database migrations ready +- [ ] Backup created + +### Deployment Steps +1. Merge feature branch to main +2. Tag release with version +3. Push to deployment service +4. Run database migrations +5. Verify deployment +6. Test critical paths +7. Monitor for errors + +### Post-Deployment +1. Monitor analytics +2. Check error logs +3. Gather user feedback +4. Plan next iteration + +## Continuous Improvement + +- Review workflow weekly +- Update based on pain points +- Document lessons learned +- Optimize for user happiness +- Keep things simple and maintainable diff --git a/docs/BUILD_LOGIC_OPTIMIZATIONS_COMPLETE.md b/docs/archive/BUILD_LOGIC_OPTIMIZATIONS_COMPLETE.md similarity index 100% rename from docs/BUILD_LOGIC_OPTIMIZATIONS_COMPLETE.md rename to docs/archive/BUILD_LOGIC_OPTIMIZATIONS_COMPLETE.md diff --git a/docs/BUILD_LOGIC_OPTIMIZATION_ANALYSIS.md b/docs/archive/BUILD_LOGIC_OPTIMIZATION_ANALYSIS.md similarity index 100% rename from docs/BUILD_LOGIC_OPTIMIZATION_ANALYSIS.md rename to docs/archive/BUILD_LOGIC_OPTIMIZATION_ANALYSIS.md diff --git a/docs/BUILD_LOGIC_OPTIMIZATION_SUMMARY.md b/docs/archive/BUILD_LOGIC_OPTIMIZATION_SUMMARY.md similarity index 100% rename from docs/BUILD_LOGIC_OPTIMIZATION_SUMMARY.md rename to docs/archive/BUILD_LOGIC_OPTIMIZATION_SUMMARY.md diff --git a/docs/kmp-status.md b/docs/kmp-status.md index c761c1b82..77ef70e20 100644 --- a/docs/kmp-status.md +++ b/docs/kmp-status.md @@ -89,6 +89,15 @@ Working Compose Desktop application with: | True multi-target readiness | ~75% | | "Add iOS without surprises" | ~65% | +## Proposed Next Steps for KMP Migration + +Based on the latest codebase investigation, the following steps are proposed to complete the multi-target and iOS-readiness migrations: + +1. **Extract remaining App-Only ViewModels:** Migrate the 5 remaining `Android*ViewModel`s by isolating their Android-specific dependencies (e.g., `android.net.Uri` for file I/O, Location permissions) behind expect/actual or injected interface abstractions. +2. **Wire Desktop Features:** Complete desktop UI wiring for `feature:intro` and implement a shared fallback for `feature:map` (which is currently a placeholder on desktop). +3. **Decouple Firmware DFU:** `feature:firmware` relies on Android-only DFU libraries. Evaluate wrapping this in a shared KMP interface or extracting it into a separate plugin to allow the core `feature:firmware` module to be fully utilized on desktop/iOS. +4. **Prepare for iOS Target:** Set up an initial skeleton Xcode project to start validating `commonMain` compilation on Kotlin/Native (iOS). + ## Key Architecture Decisions | Decision | Status | Details |