{
  "markdown": "# HermesPilot Developer Handbook\n\nWelcome to the **HermesPilot** mobile console application project. This application provides a high-fidelity client console and chat interface that syncs real-time with Hermes Agent Nodes. It is built using modern Android development practices, **Jetpack Compose** for modular UI development, and the **Room Database** for local offline-first persistence.\n\n---\n\n## 🧭 System Architecture\n\nThe application implements a standard **MVVM (Model-View-ViewModel)** design pattern, dividing roles cleanly to guarantee scalability and seamless maintenance:\n\n```\n┌────────────────────────────────────────────────────────┐\n│                      UI Layer                          │\n│     (Jetpack Compose: MainActivity & Screens)          │\n└───────────────────────────┬────────────────────────────┘\n                            │ observes StateFlows\n                            ▼\n┌────────────────────────────────────────────────────────┐\n│                    ViewModel Layer                     │\n│               (AppViewModel State Machine)             │\n└───────────────────────────┬────────────────────────────┘\n                            │ calls suspend functions\n                            ▼\n┌────────────────────────────────────────────────────────┐\n│                   Repository Layer                     │\n│               (AppRepository Coordinator)              │\n└───────────────────────────┬────────────────────────────┘\n              ┌─────────────┴─────────────┐\n              ▼                           ▼\n┌───────────────────────────┐   ┌────────────────────────┐\n│     Persistence Layer     │   │     Network Layer      │\n│ (Room SQLite DB & DAOs)   │   │ (Retrofit Client API)  │\n└───────────────────────────┘   └────────────────────────┘\n```\n\n---\n\n## 🛠️ Codebase Layout & Key Components\n\n### 1. Data Models (`com.example.data.Entities`)\n- **`ChatSession`**: Defines a conversation thread with dynamic titling and archive states (`isArchived`).\n- **`ChatMessage`**: Represents message payloads labeled as `user` or `model` (Hermes).\n- **`AppSettings`**: Consolidates layout switches, haptic statuses, and silent notifications windows.\n\n### 2. Room DAO & DB Database (`com.example.data.AppDao` / `AppDatabase`)\n- **`AppDao`**: Exposes Room query binds as reactive asynchronous **Kotlin Flows**. This achieves an offline-first responsive UI.\n- **`AppDatabase`**: Holds the local SQLite DB instance, handling version-control updates automatically.\n\n### 3. Business ViewModel (`com.example.ui.AppViewModel`)\n- Integrates database transactions under a single, unified state controller.\n- Holds the **`navigationStack`** (a mutable list of Screen structures). This acts as a robust, lightweight state navigation engine allowing fluid transitions.\n- Exposes direct tactile triggers through `triggerHaptic()` referencing Android system feedback constants.\n\n### 4. Interactive Compose Canvas (`com.example.ui.Screens`)\n- Contains detailed Material 3 widgets matching the specific visual identity shown in references:\n  - **`ChatScreen`**: Bubble list with dynamic model selector pills.\n  - **`ConsoleScreen`**: Dashboard link telemetry widget, active stats grid, and custom parameters.\n  - **`CurrentLinkScreen`**: Telemetry ping details with animated route test.\n  - **`UpdatesScreen`**: Release notes with quick update controls.\n  - **`NotificationsScreen`**: Daily silent quiet-window configuration.\n  - **`UserGuideScreen`**: Fully interactive developer documentation.\n  - **`AboutScreen`**: App details, legal terms, and contact email.\n\n---\n\n## ⚙️ Configuration & Environment Secrets\n\nAPI key injection relies on the **Secrets Gradle Plugin** mapping variables directly from local configurations without hardcoding keys inside source code:\n\n1. **AI Studio Secrets Panel**: In production, enter your **`GEMINI_API_KEY`** in the Secrets settings of AI Studio.\n2. **Local Fallback (Demo Mode)**: If no key is set, the application continues to run inside a mock fallback mode seamlessly, providing descriptive instructions to help developers set up keys without throwing execution failures.\n\n---\n\n## ⚡ Scalability & Guidelines for New Developers\n\nTo add fresh features or expand this project, adhere to these simple rules:\n\n- **State Updates**: Always emit states as immutable structures inside the ViewModel and modify them using repository coroutines.\n- **Haptic tactile feel**: If you add any button, wrap its trigger action with `viewModel.triggerHaptic(localView, HapticFeedbackConstants.KEYBOARD_TAP)` for uniform feedback.\n- **Accessibility**: Include standard Material 3 content descriptions on all icons and interactive items. Keep touch targets above **48dp**.\n- **Edge-to-Edge**: Leverage `enableEdgeToEdge()` on the Activity and handle padding values dynamically through System WindowInsets.\n",
  "bytes": 4842,
  "sha": "12cccbfece9ae29dc6da6dd2c51b0e314b8edf25891c30750bc640b0b2d7611d",
  "repo_slug": "ancientdev0x/hermes-mobile-pwa",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_ancientdev0x_hermes_mobile_pwa_okf_index_b1f8ceef/readme"
}