# imkofty/hermuse architecture

> Architecture diagram of the GitHub repository imkofty/hermuse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imkofty/hermuse
- Repository: https://github.com/imkofty/hermuse

## Overview

Hermuse combines a self-hosted Telegram AI gateway with a browser-accessible 9Router dashboard. The main chat path is Telegram to the Hermes gateway, which uses either Nous directly or local 9Router for models. Separately, browser requests reach Cloudflare Pages and are relayed through a D1-backed queue to the VM’s 9Router by a long-polling client. The README documents the operational supervisors and watchdogs; source excerpts show the tunnel’s request, polling, and response mechanics. Other runtime script internals were not sampled, so those links rely on README statements.

Main entry points: [`tunnel-client.mjs`](https://github.com/imkofty/hermuse/blob/main/tunnel-client.mjs) (Tunnel Client), [`run-hermes.sh`](https://github.com/imkofty/hermuse/blob/main/run-hermes.sh) (Hermes Gateway), [`start-9router.sh`](https://github.com/imkofty/hermuse/blob/main/start-9router.sh) (9Router), [`tunnel/schema.sql`](https://github.com/imkofty/hermuse/blob/main/tunnel/schema.sql) (D1 Queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent and Models"]
  node_hermes_gateway["Hermes Gateway<br/>[run-hermes.sh]"]
  node_nous["Nous Models"]
  node_router["9Router<br/>[start-9router.sh]"]
end

subgraph group_tunnel["Dashboard Tunnel"]
  node_pages["Pages Functions<br/>[&#91;&#91;path&#93;&#93;.js]"]
  node_queue_db[("D1 Queue<br/>[schema.sql]")]
  node_poll_endpoint["Poll Endpoint<br/>[poll.js]"]
  node_respond_endpoint["Respond Endpoint<br/>[respond.js]"]
  node_tunnel_client["Tunnel Client<br/>[tunnel-client.mjs]"]
end

subgraph group_ops["Runtime Operations"]
  node_gateway_launcher["Gateway Launcher<br/>[start-gateway.sh]"]
  node_watchdog["Service Watchdog<br/>[watchdog.sh]"]
  node_gateway_watch["Gateway Watchdog<br/>[gateway-watch.sh]"]
  node_boot_all["Boot All<br/>[start-all.sh]"]
end

node_telegram_user(("Telegram User"))
node_browser(("Browser"))

node_telegram_user -->|"chats via"| node_hermes_gateway
node_gateway_launcher -->|"starts"| node_hermes_gateway
node_hermes_gateway -->|"uses directly"| node_nous
node_hermes_gateway -->|"routes models"| node_router
node_browser -->|"requests dashboard"| node_pages
node_pages -->|"queues request"| node_queue_db
node_pages -->|"checks response"| node_queue_db
node_poll_endpoint -->|"claims requests"| node_queue_db
node_tunnel_client -->|"long-polls"| node_poll_endpoint
node_tunnel_client -->|"forwards requests"| node_router
node_tunnel_client -->|"posts responses"| node_respond_endpoint
node_respond_endpoint -->|"stores response"| node_queue_db
node_watchdog -->|"checks and restarts"| node_router
node_watchdog -->|"checks and restarts"| node_tunnel_client
node_watchdog -->|"restarts gateway"| node_gateway_launcher
node_gateway_watch -->|"checks and restarts"| node_hermes_gateway
node_boot_all -->|"starts if down"| node_router
node_boot_all -->|"starts if down"| node_tunnel_client
node_boot_all -->|"starts if down"| node_gateway_launcher

click node_gateway_launcher "https://github.com/imkofty/hermuse/blob/main/start-gateway.sh"
click node_hermes_gateway "https://github.com/imkofty/hermuse/blob/main/run-hermes.sh"
click node_router "https://github.com/imkofty/hermuse/blob/main/start-9router.sh"
click node_pages "https://github.com/imkofty/hermuse/blob/main/tunnel/pages-tunnel/functions/%5B%5Bpath%5D%5D.js"
click node_queue_db "https://github.com/imkofty/hermuse/blob/main/tunnel/schema.sql"
click node_poll_endpoint "https://github.com/imkofty/hermuse/blob/main/tunnel/pages-tunnel/functions/__tunnel/poll.js"
click node_respond_endpoint "https://github.com/imkofty/hermuse/blob/main/tunnel/pages-tunnel/functions/__tunnel/respond.js"
click node_tunnel_client "https://github.com/imkofty/hermuse/blob/main/tunnel-client.mjs"
click node_watchdog "https://github.com/imkofty/hermuse/blob/main/watchdog.sh"
click node_gateway_watch "https://github.com/imkofty/hermuse/blob/main/gateway-watch.sh"
click node_boot_all "https://github.com/imkofty/hermuse/blob/main/scripts/start-all.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hermes_gateway,node_nous,node_router,node_telegram_user,node_browser toneBlue
class node_pages,node_queue_db,node_poll_endpoint,node_respond_endpoint,node_tunnel_client toneAmber
class node_gateway_launcher,node_watchdog,node_gateway_watch,node_boot_all toneMint
```

## Components

### Agent and Models

- [Hermes Gateway](https://github.com/imkofty/hermuse/blob/main/run-hermes.sh): `run-hermes.sh`
- **Nous Models**
- [9Router](https://github.com/imkofty/hermuse/blob/main/start-9router.sh): `start-9router.sh`

### Dashboard Tunnel

- [Pages Functions](https://github.com/imkofty/hermuse/blob/main/tunnel/pages-tunnel/functions/%5B%5Bpath%5D%5D.js): `tunnel/pages-tunnel/functions/[[path]].js`
- [D1 Queue](https://github.com/imkofty/hermuse/blob/main/tunnel/schema.sql): `tunnel/schema.sql`
- [Poll Endpoint](https://github.com/imkofty/hermuse/blob/main/tunnel/pages-tunnel/functions/__tunnel/poll.js): `tunnel/pages-tunnel/functions/__tunnel/poll.js`
- [Respond Endpoint](https://github.com/imkofty/hermuse/blob/main/tunnel/pages-tunnel/functions/__tunnel/respond.js): `tunnel/pages-tunnel/functions/__tunnel/respond.js`
- [Tunnel Client](https://github.com/imkofty/hermuse/blob/main/tunnel-client.mjs): `tunnel-client.mjs`

### Runtime Operations

- [Gateway Launcher](https://github.com/imkofty/hermuse/blob/main/start-gateway.sh): `start-gateway.sh`
- [Service Watchdog](https://github.com/imkofty/hermuse/blob/main/watchdog.sh): `watchdog.sh`
- [Gateway Watchdog](https://github.com/imkofty/hermuse/blob/main/gateway-watch.sh): `gateway-watch.sh`
- [Boot All](https://github.com/imkofty/hermuse/blob/main/scripts/start-all.sh): `scripts/start-all.sh`

### Other components

- **Telegram User**
- **Browser**

## Connections

- Telegram User → Hermes Gateway: chats via (evidence: `README.md`)
- Gateway Launcher → Hermes Gateway: starts (evidence: `README.md`)
- Hermes Gateway → Nous Models: uses directly (evidence: `README.md`)
- Hermes Gateway → 9Router: routes models (evidence: `README.md`)
- Browser → Pages Functions: requests dashboard (evidence: `README.md`)
- Pages Functions → D1 Queue: queues request (evidence: `tunnel/pages-tunnel/functions/[[path]].js`)
- Pages Functions → D1 Queue: checks response (evidence: `tunnel/pages-tunnel/functions/[[path]].js`)
- Poll Endpoint → D1 Queue: claims requests (evidence: `tunnel/pages-tunnel/functions/__tunnel/poll.js`)
- Tunnel Client → Poll Endpoint: long-polls (evidence: `tunnel-client.mjs`)
- Tunnel Client → 9Router: forwards requests (evidence: `tunnel-client.mjs`)
- Tunnel Client → Respond Endpoint: posts responses (evidence: `tunnel-client.mjs`)
- Respond Endpoint → D1 Queue: stores response (evidence: `tunnel/pages-tunnel/functions/__tunnel/respond.js`)
- Service Watchdog → 9Router: checks and restarts (evidence: `README.md`)
- Service Watchdog → Tunnel Client: checks and restarts (evidence: `README.md`)
- Service Watchdog → Gateway Launcher: restarts gateway (evidence: `README.md`)
- Gateway Watchdog → Hermes Gateway: checks and restarts (evidence: `README.md`)
- Boot All → 9Router: starts if down (evidence: `README.md`)
- Boot All → Tunnel Client: starts if down (evidence: `README.md`)
- Boot All → Gateway Launcher: starts if down (evidence: `README.md`)
