Hermes Mobile PWA Knowledge
Bundle OKF 0.1 · 6 conceitos · ancientdev0x/hermes-mobile-pwa
Open source Repository Open in the app JSON README (API)
About
# Hermes Mobile PWA Knowledge
Core knowledge for building the HermesPilot Android app.
## Quick Navigation
* [Getting started](getting-started.md) - starting point
## Services
* [Hermes Link](services/hermes-link.md) - Official relay service for mobile ↔ local Hermes Agent
## Architecture
* [Android Integration Strategy](architecture/android-integration-strategy.md) - Building the UI layer with Jetpack Compose + MVVM + WebSocket
* [Phase 1 - Hermes Link Integration](implementation/phase-1-hermes-integration.md) - Replace Gemini API with Hermes Link WebSocket + streaming
## By Type
### Services
* [Hermes Link](services/hermes-link.md) — relay, pairing, conversation storage, WebSocket protocol
### Architecture Decisions
* [Android Integration Strategy](architecture/android-integration-strategy.md) — MVVM + Compose + phases, package structure, WebSocket implementation
Details
- Kind
- OKF bundles
- Topic
- AI, RAG & memory
- Publisher
- ancientdev0x
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-07-21T04:27:31Z
- Repository state
- ativo
- Language
- Kotlin
- Added
- 2026-09-08 16:04:09
- Updated
- 2026-09-08 16:04:09
- Origin id
ancientdev0x/hermes-mobile-pwa:.okf/index.md
README
# HermesPilot Developer Handbook
Welcome 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.
---
## 🧭 System Architecture
The application implements a standard **MVVM (Model-View-ViewModel)** design pattern, dividing roles cleanly to guarantee scalability and seamless maintenance:
```
┌────────────────────────────────────────────────────────┐
│ UI Layer │
│ (Jetpack Compose: MainActivity & Screens) │
└───────────────────────────┬────────────────────────────┘
│ observes StateFlows
▼
┌────────────────────────────────────────────────────────┐
│ ViewModel Layer │
│ (AppViewModel State Machine) │
└───────────────────────────┬────────────────────────────┘
│ calls suspend functions
▼
┌────────────────────────────────────────────────────────┐
│ Repository Layer │
│ (AppRepository Coordinator) │
└───────────────────────────┬────────────────────────────┘
┌─────────────┴─────────────┐
▼ ▼
┌───────────────────────────┐ ┌────────────────────────┐
│ Persistence Layer │ │ Network Layer │
│ (Room SQLite DB & DAOs) │ │ (Retrofit Client API) │
└───────────────────────────┘ └────────────────────────┘
```
---
## 🛠️ Codebase Layout & Key Components
### 1. Data Models (`com.example.data.Entities`)
- **`ChatSession`**: Defines a conversation thread with dynamic titling and archive states (`isArchived`).
- **`ChatMessage`**: Represents message payloads labeled as `user` or `model` (Hermes).
- **`AppSettings`**: Consolidates layout switches, haptic statuses, and silent notifications windows.
### 2. Room DAO & DB Database (`com.example.data.AppDao` / `AppDatabase`)
- **`AppDao`**: Exposes Room query binds as reactive asynchronous **Kotlin Flows**. This achieves an offline-first responsive UI.
- **`AppDatabase`**: Holds the local SQLite DB instance, handling version-control updates automatically.
### 3. Business ViewModel (`com.example.ui.AppViewModel`)
- Integrates database transactions under a single, unified state controller.
- Holds the **`navigationStack`** (a mutable list of Screen structures). This acts as a robust, lightweight state navigation engine allowing fluid transitions.
- Exposes direct tactile triggers through `triggerHaptic()` referencing Android system feedback constants.
### 4. Interactive Compose Canvas (`com.example.ui.Screens`)
- Contains detailed Material 3 widgets matching the specific visual identity shown in references:
- **`ChatScreen`**: Bubble list with dynamic model selector pills.
- **`ConsoleScreen`**: Dashboard link telemetry widget, active stats grid, and custom parameters.
- **`CurrentLinkScreen`**: Telemetry ping details with animated route test.
- **`UpdatesScreen`**: Release notes with quick update controls.
- **`NotificationsScreen`**: Daily silent quiet-window configuration.
- **`UserGuideScreen`**: Fully interactive developer documentation.
- **`AboutScreen`**: App details, legal terms, and contact email.
---
## ⚙️ Configuration & Environment Secrets
API key injection relies on the **Secrets Gradle Plugin** mapping variables directly from local configurations without hardcoding keys inside source code:
1. **AI Studio Secrets Panel**: In production, enter your **`GEMINI_API_KEY`** in the Secrets settings of AI Studio.
2. **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.
---
## ⚡ Scalability & Guidelines for New Developers
To add fresh features or expand this project, adhere to these simple rules:
- **State Updates**: Always emit states as immutable structures inside the ViewModel and modify them using repository coroutines.
- **Haptic tactile feel**: If you add any button, wrap its trigger action with `viewModel.triggerHaptic(localView, HapticFeedbackConstants.KEYBOARD_TAP)` for uniform feedback.
- **Accessibility**: Include standard Material 3 content descriptions on all icons and interactive items. Keep touch targets above **48dp**.
- **Edge-to-Edge**: Leverage `enableEdgeToEdge()` on the Activity and handle padding values dynamically through System WindowInsets.