# joeynyc/hermes-hudui architecture

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

- Interactive diagram: https://gitdiagram.com/joeynyc/hermes-hudui
- Repository: https://github.com/joeynyc/hermes-hudui

## Overview

1. **Overall shape**
   - This is a split Python + TypeScript application: a **FastAPI-style backend** in `backend/` and a **React/Vite frontend** in `frontend/`.
   - The app is a browser-based dashboard for a local Hermes agent installation, reading primarily from the user’s `~/.hermes/` data directory rather than from a remote cloud service.

2. **Runtime and deployment boundary**
   - The backend is the system-of-record for all Hermes data access, analytics, export, and live updates.
   - The frontend is a single-page UI that talks to backend HTTP APIs and WebSockets, and the backend also serves the built static frontend from `backend/static/`.

3. **Backend entrypoints and composition**
   - `backend/main.py` is the application entrypoint, with `backend/__init__.py` exposing the package.
   - `backend/api/` contains route modules grouped by feature area: dashboard, chat, sessions, memory, skills, projects, providers, plugins, gateway, replay, health, token costs, and more.
   - `backend/collectors/` contains the data-gathering layer for those same feature areas, which strongly suggests a pattern of “API route → collector/service → local Hermes data”.

4. **Local data ingestion layer**
   - The main data source is the Hermes local state under `~/.hermes/`, not a central database.
   - Collector modules likely parse files, logs, snapshots, and metadata from that directory into normalized responses used by the UI.
   - `backend/file_watcher.py` indicates filesystem-based change detection so the UI can react to local agent updates without manual refresh.

5. **Live update path**
   - `backend/websocket_manager.py` supports push updates to the browser.
   - The README confirms that the dashboard reacts to filesystem and WebSocket events, so the data flow is: local Hermes state changes → watcher/collector updates → WebSocket broadcast → frontend refreshes affected panels.

6. **Chat subsystem**
   - `backend/chat/` is a dedicated runtime for live agent chat, separated from dashboard data collection.
   - It includes `engine.py`, `streamer.py`, `models.py`, and a `fallback_tmux.py`, which implies the chat feature can stream responses and may fall back to terminal/tmux-based interaction when needed.
   - The frontend’s `ChatPanel` and supporting chat components consume this live stream and render reasoning/tool-call structure, not just plain messages.

7. **Replay pipeline**
   - Replay is a distinct subsystem with its own model, normalization, redaction, signing, verification, and export flow.
   - `backend/models/replay.py` defines the replay data model; `backend/services/replay_normalizer.py`, `replay_redactor.py`, `replay_exporter.py`, `replay_signer.py`, and `replay_verifier.py` form a pipeline for turning raw session data into shareable artifacts.
   - This is a key architectural boundary: raw agent traces are transformed into sanitized, signed outputs before export.

8. **Replay and shareability boundary**
   - The README emphasizes “Safe Share Mode” and local-only exports under `~/.hermes-hud/replays/`.
   - That means the replay feature is intentionally designed to avoid uploading sensitive agent content by default; redaction and signing happen locally, and signature integrity is machine-local rather than third-party attested.

9. **Feature-domain collectors and APIs**
   - The feature modules in `backend/api/` and `backend/collectors/` mirror each other: agents, corrections, cron, gateway, health, memory, model_info, patterns, plugins, profiles, projects, providers, sessions, skills, sudo, timeline, and token_costs.
   - This suggests a modular architecture where each domain has:
     - a collector that reads or derives local state,
     - an API route that serializes it for the UI,
     - and a corresponding frontend panel.

10. **Caching, serialization, and state**
   - `backend/cache.py` and `backend/api/cache.py` indicate explicit caching around expensive local queries.
   - `backend/api/serialize.py` and `backend/api/state.py` imply a normalization/serialization layer for presenting heterogeneous Hermes data consistently to the browser.
   - This matters because the dashboard mixes static metadata with expensive summaries and live status, so not every UI action should recompute from scratch.

11. **Health, diagnostics, and governance**
   - Health, gateway, sudo, and corrections are treated as first-class operational concerns.
   - `backend/api/health.py`, `gateway.py`, `sudo.py`, and `corrections.py` indicate the dashboard is not just observability; it also exposes control surfaces and safeguards around agent operation, tool routing, and privileged actions.
   - The README’s “two-click Update hermes” and gateway visibility reinforce that some actions are intentionally gated.

12. **Frontend structure**
   - The frontend is organized into feature panels in `frontend/src/components/`, with shared shell pieces like `TopBar`, `BootScreen`, `CommandPalette`, and a generic `Panel`.
   - `frontend/src/components/chat/` contains specialized chat rendering for reasoning blocks, tool-call cards, message threading, and session sidebars.
   - `frontend/src/hooks/` centralizes API access, WebSocket subscription, theme handling, and chat state, which keeps the panels mostly presentational.

13. **User experience and state propagation**
   - `frontend/src/i18n/` shows built-in localization, and theme support is handled client-side with persistent preference storage.
   - `frontend/src/lib/replayApi.ts` and `frontend/src/types/replay.ts` reflect a typed integration for the replay domain specifically.
   - The UI is therefore driven by backend data contracts, but retains local UX state such as language, theme, and panel navigation in the browser.

14. **External dependencies and tooling**
   - The project is Python 3.11+ on the backend and Node.js 18+ for the frontend build.
   - `pyproject.toml`, `frontend/vite.config.ts`, and `ci.yml` show standard packaging/build automation, while tests cover both backend logic and browser-facing behavior.
   - The only “external services” materially implied by the architecture are Hermes itself, local OAuth/provider integrations, and the Nous tool gateway used for managed tool routing.

15. **How to diagram it**
   - A good architecture diagram would place **Hermes local data (`~/.hermes/`)** at the center, feeding the **collector/service layer** in the Python backend.
   - From there, branch to:
     - **REST APIs** for each domain,
     - **WebSocket live updates** for dashboard/chat refresh,
     - **Replay export/sign/verify pipeline** for shareable artifacts,
     - and the **React SPA** as the presentation layer.
   - The main boundary is between **read/transform/control logic in Python** and **interactive visualization in the browser**.

Main entry points: [`backend/api`](https://github.com/joeynyc/hermes-hudui/tree/main/backend/api) (API routes), [`backend/collectors`](https://github.com/joeynyc/hermes-hudui/tree/main/backend/collectors) (Collectors), [`backend/main.py`](https://github.com/joeynyc/hermes-hudui/blob/main/backend/main.py) (Main app), [`frontend/src/App.tsx`](https://github.com/joeynyc/hermes-hudui/blob/main/frontend/src/App.tsx) (SPA shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_main_entry["Main app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_file_watcher["File watcher<br/>fs monitor<br/>[file_watcher.py]"]
  node_ws_manager["WebSocket hub<br/>push updates"]
  node_cache_layer["Cache<br/>[cache.py]"]
  node_collectors["Collectors<br/>data ingestion"]
  node_api_routes["API routes<br/>HTTP surface"]
  node_serialize_state["Serialize state<br/>presentation layer<br/>[serialize.py]"]
  node_chat_runtime["Chat runtime<br/>streaming chat"]
end

subgraph group_frontend["Frontend"]
  node_spa_shell["SPA shell<br/>React app<br/>[App.tsx]"]
  node_ui_hooks["UI hooks<br/>client state"]
  node_panels["Panels<br/>dashboard views"]
  node_chat_ui["Chat UI<br/>chat views"]
  node_replay_ui["Replay UI<br/>replay client<br/>[replayApi.ts]"]
end

subgraph group_replay["Replay pipeline"]
  node_replay_model["Replay model<br/>session trace model<br/>[replay.py]"]
  node_replay_norm["Normalize<br/>transform"]
  node_replay_redact["Redact<br/>privacy filter<br/>[replay_redactor.py]"]
  node_replay_sign["Sign<br/>integrity step<br/>[replay_signer.py]"]
  node_replay_verify["Verify<br/>integrity check<br/>[replay_verifier.py]"]
  node_replay_export["Export<br/>artifact writer<br/>[replay_exporter.py]"]
end

node_hermes_data[("Hermes data<br/>local state")]

node_hermes_data -->|"read local state"| node_collectors
node_file_watcher -->|"emit changes"| node_ws_manager
node_collectors -->|"memoize"| node_cache_layer
node_collectors -->|"normalize"| node_serialize_state
node_main_entry -->|"mount routes"| node_api_routes
node_main_entry -->|"start chat"| node_chat_runtime
node_main_entry -->|"init push"| node_ws_manager
node_api_routes -->|"serve data"| node_collectors
node_api_routes -->|"shape payloads"| node_serialize_state
node_api_routes -->|"chat stream"| node_chat_runtime
node_ws_manager -->|"push live data"| node_ui_hooks
node_api_routes -->|"http api"| node_spa_shell
node_ui_hooks -->|"feed views"| node_panels
node_ui_hooks -->|"drive chat"| node_chat_ui
node_spa_shell -->|"render app"| node_panels
node_spa_shell -->|"render chat"| node_chat_ui
node_replay_model -->|"input model"| node_replay_norm
node_replay_norm -->|"sanitize"| node_replay_redact
node_replay_redact -->|"seal"| node_replay_sign
node_replay_sign -->|"check"| node_replay_verify
node_replay_verify -->|"approve export"| node_replay_export
node_api_routes -->|"replay api"| node_replay_model
node_replay_export -->|"browse artifacts"| node_replay_ui
node_api_routes -->|"replay api"| node_replay_ui

click node_main_entry "https://github.com/joeynyc/hermes-hudui/blob/main/backend/main.py"
click node_file_watcher "https://github.com/joeynyc/hermes-hudui/blob/main/backend/file_watcher.py"
click node_ws_manager "https://github.com/joeynyc/hermes-hudui/blob/main/backend/websocket_manager.py"
click node_cache_layer "https://github.com/joeynyc/hermes-hudui/blob/main/backend/cache.py"
click node_collectors "https://github.com/joeynyc/hermes-hudui/tree/main/backend/collectors"
click node_api_routes "https://github.com/joeynyc/hermes-hudui/tree/main/backend/api"
click node_serialize_state "https://github.com/joeynyc/hermes-hudui/blob/main/backend/api/serialize.py"
click node_chat_runtime "https://github.com/joeynyc/hermes-hudui/tree/main/backend/chat"
click node_replay_model "https://github.com/joeynyc/hermes-hudui/blob/main/backend/models/replay.py"
click node_replay_norm "https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_normalizer.py"
click node_replay_redact "https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_redactor.py"
click node_replay_sign "https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_signer.py"
click node_replay_verify "https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_verifier.py"
click node_replay_export "https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_exporter.py"
click node_spa_shell "https://github.com/joeynyc/hermes-hudui/blob/main/frontend/src/App.tsx"
click node_ui_hooks "https://github.com/joeynyc/hermes-hudui/tree/main/frontend/src/hooks"
click node_panels "https://github.com/joeynyc/hermes-hudui/tree/main/frontend/src/components"
click node_chat_ui "https://github.com/joeynyc/hermes-hudui/tree/main/frontend/src/components/chat"
click node_replay_ui "https://github.com/joeynyc/hermes-hudui/blob/main/frontend/src/lib/replayApi.ts"

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_main_entry,node_file_watcher,node_ws_manager,node_cache_layer,node_collectors,node_api_routes,node_serialize_state,node_chat_runtime toneBlue
class node_spa_shell,node_ui_hooks,node_panels,node_chat_ui,node_replay_ui toneAmber
class node_replay_model,node_replay_norm,node_replay_redact,node_replay_sign,node_replay_verify,node_replay_export toneMint
class node_hermes_data toneNeutral
```

## Components

### Backend

Python API, collectors, chat runtime, and replay services.

- [Main app](https://github.com/joeynyc/hermes-hudui/blob/main/backend/main.py): FastAPI entrypoint · Application startup and backend composition. · `backend/main.py`
- [File watcher](https://github.com/joeynyc/hermes-hudui/blob/main/backend/file_watcher.py): fs monitor · Detects local Hermes changes for live dashboard updates. · `backend/file_watcher.py`
- [WebSocket hub](https://github.com/joeynyc/hermes-hudui/blob/main/backend/websocket_manager.py): push updates · Broadcasts live state changes to connected browsers. · `backend/websocket_manager.py`
- [Cache](https://github.com/joeynyc/hermes-hudui/blob/main/backend/cache.py): query cache · Shared caching around expensive local reads and summaries. · `backend/cache.py`
- [Collectors](https://github.com/joeynyc/hermes-hudui/tree/main/backend/collectors): data ingestion · Feature-specific readers that normalize local Hermes state. · `backend/collectors`
- [API routes](https://github.com/joeynyc/hermes-hudui/tree/main/backend/api): HTTP surface · Feature modules exposing dashboard, chat, sessions, memory, providers, replay, health, and other endpoints. · `backend/api`
- [Serialize state](https://github.com/joeynyc/hermes-hudui/blob/main/backend/api/serialize.py): presentation layer · Normalization and serialization of heterogeneous backend data for the UI. · `backend/api/serialize.py`
- [Chat runtime](https://github.com/joeynyc/hermes-hudui/tree/main/backend/chat): streaming chat · Dedicated live agent chat engine with streaming and tmux fallback. · `backend/chat`

### Frontend

React/Vite single-page dashboard and panel system.

- [SPA shell](https://github.com/joeynyc/hermes-hudui/blob/main/frontend/src/App.tsx): React app · Top-level frontend application and panel routing. · `frontend/src/App.tsx`
- [UI hooks](https://github.com/joeynyc/hermes-hudui/tree/main/frontend/src/hooks): client state · Browser-side hooks for API access, WebSocket subscriptions, chat state, and theme handling. · `frontend/src/hooks`
- [Panels](https://github.com/joeynyc/hermes-hudui/tree/main/frontend/src/components): dashboard views · Feature panels for dashboard, chat, sessions, replay, health, gateway, memory, and other domains. · `frontend/src/components`
- [Chat UI](https://github.com/joeynyc/hermes-hudui/tree/main/frontend/src/components/chat): chat views · Specialized chat rendering for reasoning, tool calls, threads, and session context. · `frontend/src/components/chat`
- [Replay UI](https://github.com/joeynyc/hermes-hudui/blob/main/frontend/src/lib/replayApi.ts): replay client · Typed frontend integration for replay browsing and verification. · `frontend/src/lib/replayApi.ts`

### Replay pipeline

Normalization, redaction, signing, verification, and export for shareable session artifacts.

- [Replay model](https://github.com/joeynyc/hermes-hudui/blob/main/backend/models/replay.py): session trace model · Core replay data structure used across the replay pipeline. · `backend/models/replay.py`
- [Normalize](https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_normalizer.py): transform · Converts raw session data into a replayable normalized form. · `backend/services/replay_normalizer.py`
- [Redact](https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_redactor.py): privacy filter · Removes or masks sensitive content before sharing. · `backend/services/replay_redactor.py`
- [Sign](https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_signer.py): integrity step · Adds local signature metadata to replay artifacts. · `backend/services/replay_signer.py`
- [Verify](https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_verifier.py): integrity check · Checks replay signatures and artifact validity. · `backend/services/replay_verifier.py`
- [Export](https://github.com/joeynyc/hermes-hudui/blob/main/backend/services/replay_exporter.py): artifact writer · Writes local replay outputs for safe sharing. · `backend/services/replay_exporter.py`

### Other components

- **Hermes data**: local state · Local Hermes files and state under the user's ~/.hermes/ directory.

## Connections

- Hermes data → Collectors: read local state · Collectors parse files, logs, snapshots, and metadata from Hermes local storage.
- File watcher → WebSocket hub: emit changes · Filesystem events trigger update broadcasts.
- Collectors → Cache: memoize · Expensive derived reads are cached.
- Collectors → Serialize state: normalize · Collected domain data is shaped for API responses.
- Main app → API routes: mount routes · Backend entrypoint composes the HTTP surface.
- Main app → Chat runtime: start chat · Backend entrypoint includes the live chat subsystem.
- Main app → WebSocket hub: init push · WebSocket manager is part of backend runtime coordination.
- API routes → Collectors: serve data · Feature endpoints delegate to collectors or services.
- API routes → Serialize state: shape payloads · API responses are serialized consistently for the browser.
- API routes → Chat runtime: chat stream · Chat endpoints expose the live agent stream.
- WebSocket hub → UI hooks: push live data · Browser subscriptions receive panel and chat updates.
- API routes → SPA shell: http api · The SPA consumes backend endpoints.
- UI hooks → Panels: feed views · Hooks supply data and actions to feature panels.
- UI hooks → Chat UI: drive chat · Chat state and streaming updates power the chat interface.
- SPA shell → Panels: render app · The top-level app composes the dashboard panels and shell.
- SPA shell → Chat UI: render chat · Chat experience is embedded in the SPA.
- Replay model → Normalize: input model · Raw replay traces are normalized around the shared model.
- Normalize → Redact: sanitize · Normalized traces are redacted before sharing.
- Redact → Sign: seal · Redacted artifacts are signed locally.
- Sign → Verify: check · Signatures and artifacts can be verified locally.
- Verify → Export: approve export · Verified artifacts are exported for safe sharing.
- API routes → Replay model: replay api · Replay endpoints expose the session trace domain.
- Export → Replay UI: browse artifacts · Frontend replay views consume replay artifacts and status.
- API routes → Replay UI: replay api · The replay UI talks to dedicated backend replay endpoints.