ARIA
746d809d48
- IRIS_PUSH_BACKEND now defaults to ntfy (keeps push metadata on your own infrastructure); FCM is opt-in via IRIS_PUSH_BACKEND=fcm - build_push_backend(): ntfy for empty/unknown names, FCM only on explicit 'fcm' - gateway setup: warn when FCM is chosen (metadata routed via Google's servers) - README: privacy note + dedicated push section; new docs/playstore-listing.md with the FCM/ntfy privacy note for the Play Store listing - docs: 00/02/03/08/12/16 + setup.md updated to ntfy-default wording - tests: default-backend assertion updated (86/86 pass)
74 lines
4.1 KiB
Markdown
74 lines
4.1 KiB
Markdown
# Iris × Hermes — Implementation Reference Library
|
||
|
||
A coder-facing reference library for building a **native Android + Desktop
|
||
experience** for [hermes-agent](https://github.com/NousResearch/hermes-agent),
|
||
connected through a **gateway platform plugin**.
|
||
|
||
This folder is the single source of truth for *what to build and why*. Read it
|
||
top-to-bottom once, then use the numbered docs as a lookup while implementing.
|
||
|
||
> ⚠️ **READ FIRST — two hard rules**
|
||
>
|
||
> 1. **`hermes-agent/` (sibling of this folder) is a read-only research
|
||
> reference. It must NEVER be committed, pushed, or shipped.** It is
|
||
> git-ignored at the repo root. We only *install* our plugin into a live
|
||
> hermes install (`~/.hermes/plugins/`); we never modify hermes core.
|
||
> 2. **ADB is installed and a device is connected** (`a5ca2a4b`, Xiaomi MIX 2S,
|
||
> Android 10 / API 29). Use it to install/launch/debug the app on-device.
|
||
|
||
---
|
||
|
||
## Reading order
|
||
|
||
| # | File | When to read |
|
||
| --- | ------ | -------------- |
|
||
| 0 | [`00-overview.md`](00-overview.md) | Always first. Vision, scope, disclaimers, locked decisions. |
|
||
| 1 | [`01-architecture.md`](01-architecture.md) | Before touching code. System shape + rationale. |
|
||
| 2 | [`02-monorepo.md`](02-monorepo.md) | When scaffolding the repo. |
|
||
| 3 | [`03-gateway-plugin.md`](03-gateway-plugin.md) | When building the Python plugin. |
|
||
| 4 | [`04-wire-protocol.md`](04-wire-protocol.md) | When implementing either side of the WS. |
|
||
| 5 | [`05-streaming.md`](05-streaming.md) | Streaming / reasoning / tools / intermediate. |
|
||
| 6 | [`06-channels-cron-search.md`](06-channels-cron-search.md) | Channels, threads, cron delivery, search. |
|
||
| 7 | [`07-media.md`](07-media.md) | Media upload/download + playback. |
|
||
| 8 | [`08-push.md`](08-push.md) | Push (ntfy default + FCM optional), outbox, sync. |
|
||
| 9 | [`09-pairing-security.md`](09-pairing-security.md) | Pairing, auth, security model. |
|
||
| 10 | [`10-android-app.md`](10-android-app.md) | When building the Android app. |
|
||
| 11 | [`11-desktop-app.md`](11-desktop-app.md) | When building the Desktop app. |
|
||
| 12 | [`12-toolchain.md`](12-toolchain.md) | First time on a machine (JDK/SDK/uv/Firebase). |
|
||
| 13 | [`13-testing.md`](13-testing.md) | Writing tests + on-device ADB workflow. |
|
||
| 14 | [`14-milestones.md`](14-milestones.md) | Planning work / tracking progress. |
|
||
| 15 | [`15-hermes-reference.md`](15-hermes-reference.md) | **Cheat-sheet** of hermes-agent source to read. |
|
||
| 16 | [`16-open-questions.md`](16-open-questions.md) | Decisions made + open items. |
|
||
| 17 | [`17-future-control-surface.md`](17-future-control-surface.md) | **Backlog** — what the app could control beyond chat (cron, kanban, models, …). |
|
||
| 19 | [`19-http-fallback-transport.md`](19-http-fallback-transport.md) | **Design** — HTTP fallback leg (POST + SSE/long-poll) so the app can send/receive when the WS is down. |
|
||
| 20 | [`20-qr-pairing.md`](20-qr-pairing.md) | Terminal QR at `gateway setup` + in-app QR scanner (Android) + `iris://pair` deep link. |
|
||
|
||
Machine-readable / diagrams:
|
||
|
||
- [`protocol/frames.schema.json`](protocol/frames.schema.json) — wire-frame schema.
|
||
- [`diagrams/architecture.mmd`](diagrams/architecture.mmd) — mermaid architecture.
|
||
- [`playstore-listing.md`](playstore-listing.md) — Play Store listing text (incl. the FCM/ntfy privacy note).
|
||
|
||
---
|
||
|
||
## The three deliverables (one monorepo)
|
||
|
||
1. **`gateway-plugin/`** — a Python hermes **platform plugin** named `iris`.
|
||
Runs inside the `hermes gateway` process. Opens a WebSocket server the apps
|
||
connect to. Implements the full `BasePlatformAdapter` contract. **Zero new
|
||
Python dependencies, zero hermes-core changes.**
|
||
2. **`app/androidApp`** — native Kotlin + Jetpack Compose client.
|
||
3. **`app/desktopApp`** — Kotlin + Compose Multiplatform client that *shares*
|
||
the Android app's code and is "tweaked" for a big screen.
|
||
|
||
The Android and Desktop clients live in **one Compose Multiplatform Gradle
|
||
project** (`app/`) with a shared KMP module (`app/shared`).
|
||
|
||
---
|
||
|
||
## Status
|
||
|
||
- **Phase:** M0–M6 complete; M7 (polish + E2E + docs) in progress.
|
||
- **Owner decisions locked:** see [`16-open-questions.md`](16-open-questions.md).
|
||
- **Last updated:** 2026-08-19.
|