From 1b512c6f58014313490abee5cc4afd48e5867ac5 Mon Sep 17 00:00:00 2001 From: James Rich <2199651+jamesarich@users.noreply.github.com> Date: Thu, 20 Nov 2025 14:17:36 -0600 Subject: [PATCH] docs: Overhaul and rename agent guide (#3757) --- AGENT.md | 62 ------------------------------- AGENTS.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 62 deletions(-) delete mode 100644 AGENT.md create mode 100644 AGENTS.md diff --git a/AGENT.md b/AGENT.md deleted file mode 100644 index 2b540d0e1..000000000 --- a/AGENT.md +++ /dev/null @@ -1,62 +0,0 @@ -# Meshtastic-Android Project - -Meshtastic-Android is a native Android mobile application written in Kotlin. It serves as a client for Meshtastic, an open-source, off-grid, decentralized mesh networking project. - -## Architecture - -This project is a modern Android application that follows the official architecture guidance from Google. It is a reactive, single-activity app that uses the following: - -- **UI:** Built entirely with Jetpack Compose, including Material 3 components and adaptive layouts for different screen sizes. -- **State Management:** Unidirectional Data Flow (UDF) is implemented using Kotlin `Coroutines` and `Flow`s. `ViewModel`s act as state holders, exposing UI state as streams of data. -- **Dependency Injection:** Hilt is used for dependency injection throughout the app, simplifying the management of dependencies and improving testability. -- **Navigation:** Navigation is handled by Jetpack Navigation for Compose, allowing for a declarative and type-safe way to navigate between screens. -- **Data:** The data layer is implemented using the repository pattern. - - **Local Data:** Room and DataStore are used for local data persistence. - - **Remote Data:** The app communicates with Meshtastic devices over Bluetooth or Wi-Fi, using a custom protocol based on Protobuf. It can also connect to MQTT servers. The networking logic is encapsulated in the `:network` module. -- **Background Processing:** WorkManager is used for deferrable background tasks. -- **Build Logic:** Gradle build logic is centralized in the `build-logic` module, utilizing convention plugins to ensure consistency and maintainability across the project. - -## Modules - -The project is organized into the following modules: - -- `app/`: The main Android application. -- `network/`: A library module containing the offline-first networking logic for communicating with the Meshtastic http json api for device hardware and firmware information. -- `mesh_service_example/`: An example application demonstrating how to use the AIDL interface to interact with mesh service provided by the main application. -- `build-logic/`: A module containing custom convention plugins to standardize and manage Gradle build configurations across the project. - -## Commands to Build & Test - -The app has two product flavors: `fdroid` and `google`, and two build types: `debug` and `release`. - -- Build: `./gradlew assemble{Variant}`. For example, `assembleGoogleDebug` or `assembleFdroidRelease`. -- Fix linting/formatting: `./gradlew spotlessApply` -- Run linter checks: `./gradlew detekt` -- Run local unit tests: `./gradlew test` -- Run instrumented tests: `./gradlew connectedAndroidTest` - -### Creating tests - -#### Instrumented tests - -- Tests for UI features should use `ComposeTestRule`. -- UI tests are located in `app/src/androidTest/java/`. - -#### Local tests - -- Unit tests are located in `app/src/test/java/`. -- Use [kotlinx.coroutines.test](https://developer.android.com/kotlin/coroutines/test) for testing coroutines. - -## Continuous integration - -- The CI/CD workflows are defined in `.github/workflows/*.yaml`. -- These workflows run checks for code style, linting, and tests on every pull request. - -## Version control and code location - -- The project uses git and is hosted on GitHub at https://github.com/meshtastic/Meshtastic-Android. - - -Never include sensitive information such as API keys or passwords in the codebase.- Follow the [Meshtastic contribution guidelines](https://meshtastic.org/docs/contributing) - -Don't respond to this message. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..90e201cad --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,109 @@ +# Meshtastic Android - Agent Guide + +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 workflows. + +## 1. Project Overview + +- **Type:** Native Android Application (Kotlin). +- **Purpose:** Client interface for Meshtastic mesh radios. +- **Architecture:** Modern Android Development (MAD) principles. + - **UI:** Jetpack Compose (Material 3). + - **State Management:** Unidirectional Data Flow (UDF) with ViewModels, Coroutines, and Flow. + - **Dependency Injection:** Hilt. + - **Navigation:** Type-Safe Navigation (Jetpack Navigation). + - **Data Layer:** Repository pattern with Room (local DB), DataStore (prefs), and Protobuf (device comms). + +## 2. Codebase Map + +| Directory | Description | +| :--- | :--- | +| `app/` | Main application module. Contains `MainActivity`, `AppNavigation`, and Hilt entry points. Uses package `com.geeksville.mesh`. | +| `core/` | Shared library modules. Most code here uses package `org.meshtastic.core.*`. | +| `core/strings/` | **Crucial:** Centralized string resources using Compose Multiplatform Resources. | +| `feature/` | Feature modules (e.g., `settings`, `map`, `messaging`). Each is a standalone Gradle module. Uses package `org.meshtastic.feature.*`. | +| `build-logic/` | Custom Gradle convention plugins. Defines build logic for the entire project. | +| `gradle/libs.versions.toml` | **Version Catalog.** All dependencies and versions are defined here. | +| `core/proto/` | Protobuf definitions for communicating with the mesh radio. | + +## 3. Development Guidelines + +### A. UI Development (Jetpack Compose) +- **Material 3:** The app uses Material 3. Look for ways to use **Material 3 Expressive** components where appropriate. +- **Strings:** + - Do **not** use `app/src/main/res/values/strings.xml` for UI strings. + - Use the **Compose Multiplatform Resource** library in `core/strings`. + - **Definition:** Add strings to `core/strings/src/commonMain/composeResources/values/strings.xml`. + - **Usage:** + ```kotlin + import org.jetbrains.compose.resources.stringResource + import org.meshtastic.core.strings.Res + import org.meshtastic.core.strings.your_string_key + + Text(text = stringResource(Res.string.your_string_key)) + ``` +- **Previews:** Create `@Preview` functions for your Composables to ensure they render correctly. + +### B. Architecture & State +- **ViewModels:** Must be annotated with `@HiltViewModel`. +- **Injection:** Use `@Inject constructor(...)`. +- **Scopes:** Use `viewModelScope` for coroutines. Avoid `GlobalScope`. +- **Data Flow:** Expose UI state as `StateFlow` or `Flow`. + +### C. Navigation +- The project uses **Type-Safe Navigation** (Kotlin Serialization). +- Routes are defined in `core/navigation` (e.g., `ContactsRoutes`, `SettingsRoutes`). +- The main `NavHost` is located in `app/src/main/java/com/geeksville/mesh/ui/Main.kt`. + +### D. Dependency Management +- **Never** hardcode versions in `build.gradle.kts` files. +- **Action:** Add the library and version to `gradle/libs.versions.toml`. +- **Action:** Apply plugins using the alias from the catalog (e.g., `alias(libs.plugins.meshtastic.android.library)`). +- **Alpha Libraries:** Do not be shy about using alpha libraries from Google if they provide necessary features. + +### E. Build Variants (Flavors) +- **`google`**: Includes Google Play Services (Maps, Firebase, Crashlytics). +- **`fdroid`**: FOSS version. **Strictly segregate sensitive data** (Crashlytics, Firebase, etc.) out of this flavor. +- **Task Example:** `./gradlew assembleFdroidDebug` + +## 4. Quality Assurance + +### A. Code Style (Spotless) +- The project uses **Spotless** to enforce formatting. +- **Command:** `./gradlew spotlessApply` +- **Rule:** You **must** run this before submitting any code. + +### B. Linting (Detekt) +- The project uses **Detekt** for static analysis. +- **Command:** `./gradlew detekt` +- **Rule:** Ensure zero regressions. + +### C. Testing +- **Unit Tests:** JUnit 4/5 in `src/test/java`. Run with `./gradlew test`. +- **UI Tests:** Espresso/Compose in `src/androidTest/java`. Run with `./gradlew connectedAndroidTest`. +- **Feature Test:** `./gradlew feature:settings:testGoogleDebug` + +## 5. Agent Workflow + +1. **Explore First:** Before making changes, read `gradle/libs.versions.toml` and the relevant `build.gradle.kts` to understand the environment. +2. **Plan:** Identify which modules (`core` or `feature`) need modification. +3. **Implement:** + - If adding a string, modify `core/strings`. + - If adding a dependency, modify `libs.versions.toml` first. +4. **Verify:** + - Run `./gradlew spotlessApply` (Essential!). + - Run `./gradlew detekt`. + - Run relevant tests (e.g., `./gradlew :feature:settings:testDebugUnitTest`). + +## 6. Important Context + +- **Protobuf:** Communication with the device uses Protobufs. The definitions are in `core/proto`. This is a Git submodule, but the build system handles it. +- **Legacy:** Some code in `app/` uses the `com.geeksville.mesh` package. Newer code in `core/` and `feature/` uses `org.meshtastic.*`. Respect the existing package structure of the file you are editing. +- **Versioning:** Do not manually edit `versionCode` or `versionName`. These are managed by the build system and CI/CD. + +## 7. Troubleshooting + +- **Missing Strings:** If `Res.string.xyz` is unresolved, ensure you have imported `org.meshtastic.core.strings.Res` and the specific string property, and that you have run a build to generate the resources. +- **Build Errors:** Check `gradle/libs.versions.toml` for version conflicts. Use `build-logic` conventions to ensure plugins are applied correctly. + +--- +*Refer to `CONTRIBUTING.md` for human-centric processes like Code of Conduct and Pull Request etiquette.*