# aprazdnikov/agent-hub-rs architecture

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

- Interactive diagram: https://gitdiagram.com/aprazdnikov/agent-hub-rs
- Repository: https://github.com/aprazdnikov/agent-hub-rs

## Overview

agent-hub is a cross-platform desktop app that routes Telegram forum topics to persistent local AI-agent sessions. The main workflow is Telegram update intake, topic/session orchestration, agent execution, and result delivery; settings, projects, approvals, attachments, voice, handoff, snapshots, and outbox handling are additional product capabilities. The graph combines README-documented behavior with sampled source and source-index references; several subsystem links are documented rather than verified from full implementations.

Main entry points: [`crates/hub-telegram/src/hub.rs`](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/hub.rs) (Topic hub), [`crates/hub-agent/src/channel.rs`](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-agent/src/channel.rs) (Agent channel), [`crates/hub-telegram/src/session.rs`](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/session.rs) (Topic session), [`crates/hub-telegram/src/telegram.rs`](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/telegram.rs) (Bot listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_desktop_ui["Settings window<br/>[app.rs]"]
  node_app_supervisor["Bot supervisor<br/>[supervisor.rs]"]
end

subgraph group_telegram["Telegram interface"]
  node_telegram{{"Telegram Bot API"}}
  node_telegram_adapter["Bot listener<br/>[telegram.rs]"]
  node_inbound["Update conversion<br/>[inbound.rs]"]
  node_sender["Delivery policy<br/>[sender.rs]"]
  node_messenger["Messenger API<br/>[messenger.rs]"]
  node_download["Attachment download<br/>[download.rs]"]
end

subgraph group_workflow["Session workflow"]
  node_core_settings["Settings and projects<br/>[settings.rs]"]
  node_hub["Topic hub<br/>[hub.rs]"]
  node_topic_session["Topic session<br/>[session.rs]"]
end

subgraph group_agents["Agent runtimes"]
  node_agent_channel["Agent channel<br/>[channel.rs]"]
  node_claude["Claude runtime<br/>[session.rs]"]
  node_codex["Codex runtime<br/>[backend.rs]"]
  node_qwen["Qwen runtime<br/>[session.rs]"]
  node_hermes["Hermes runtime<br/>[backend.rs]"]
  node_opencode["OpenCode runtime<br/>[backend.rs]"]
end

subgraph group_capabilities["Workflow capabilities"]
  node_progress["Progress reporting<br/>[progress.rs]"]
  node_result_delivery["Result delivery<br/>[results.rs]"]
  node_snapshots["History snapshots<br/>[snapshots.rs]"]
  node_handoff["Agent handoff<br/>[handoff.rs]"]
  node_outbox[("Retry outbox<br/>[outbox.rs]")]
  node_actions["Preset actions<br/>[actions.rs]"]
  node_voice["Voice transcription<br/>[voice.rs]"]
end

node_user(("Phone user"))

node_user -->|"sends task"| node_telegram
node_desktop_ui -.->|"configures"| node_core_settings
node_desktop_ui -->|"controls"| node_app_supervisor
node_app_supervisor -.->|"starts bot"| node_hub
node_telegram -->|"delivers updates"| node_telegram_adapter
node_telegram_adapter -->|"converts updates"| node_inbound
node_telegram_adapter -.->|"routes events"| node_hub
node_hub -->|"starts session"| node_topic_session
node_topic_session -->|"downloads attachments"| node_download
node_topic_session -->|"runs agent"| node_agent_channel
node_agent_channel -.->|"dispatches"| node_claude
node_agent_channel -.->|"dispatches"| node_codex
node_agent_channel -.->|"dispatches"| node_qwen
node_agent_channel -.->|"dispatches"| node_hermes
node_agent_channel -.->|"dispatches"| node_opencode
node_topic_session -->|"reports events"| node_progress
node_topic_session -->|"relays results"| node_result_delivery
node_hub -.->|"sends responses"| node_sender
node_sender -->|"applies policy"| node_messenger
node_messenger -.->|"sends messages"| node_telegram
node_hub -->|"saves history"| node_snapshots
node_hub -.->|"handles handoff"| node_handoff
node_hub -.->|"manages delivery"| node_outbox
node_hub -.->|"runs commands"| node_actions
node_hub -.->|"handles voice"| node_voice
node_core_settings -.->|"configures workflow"| node_hub

click node_desktop_ui "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-app/src/gui/app.rs"
click node_app_supervisor "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-app/src/supervisor.rs"
click node_core_settings "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-core/src/settings.rs"
click node_telegram_adapter "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/telegram.rs"
click node_inbound "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/inbound.rs"
click node_hub "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/hub.rs"
click node_topic_session "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/session.rs"
click node_agent_channel "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-agent/src/channel.rs"
click node_claude "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-claude/src/session.rs"
click node_codex "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-codex/src/backend.rs"
click node_qwen "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-qwen/src/session.rs"
click node_hermes "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-hermes/src/backend.rs"
click node_opencode "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-opencode/src/backend.rs"
click node_sender "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/sender.rs"
click node_messenger "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/messenger.rs"
click node_download "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/download.rs"
click node_progress "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/progress.rs"
click node_result_delivery "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/results.rs"
click node_snapshots "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/snapshots.rs"
click node_handoff "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/handoff.rs"
click node_outbox "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/outbox.rs"
click node_actions "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/actions.rs"
click node_voice "https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/voice.rs"

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_desktop_ui,node_app_supervisor,node_user toneBlue
class node_telegram,node_telegram_adapter,node_inbound,node_sender,node_messenger,node_download toneAmber
class node_core_settings,node_hub,node_topic_session toneMint
class node_agent_channel,node_claude,node_codex,node_qwen,node_hermes,node_opencode toneRose
class node_progress,node_result_delivery,node_snapshots,node_handoff,node_outbox,node_actions,node_voice toneIndigo
```

## Components

### Desktop app

- [Settings window](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-app/src/gui/app.rs): `crates/hub-app/src/gui/app.rs`
- [Bot supervisor](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-app/src/supervisor.rs): `crates/hub-app/src/supervisor.rs`

### Telegram interface

- **Telegram Bot API**
- [Bot listener](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/telegram.rs): `crates/hub-telegram/src/telegram.rs`
- [Update conversion](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/inbound.rs): `crates/hub-telegram/src/inbound.rs`
- [Delivery policy](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/sender.rs): `crates/hub-telegram/src/sender.rs`
- [Messenger API](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/messenger.rs): `crates/hub-telegram/src/messenger.rs`
- [Attachment download](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/download.rs): `crates/hub-telegram/src/download.rs`

### Session workflow

- [Settings and projects](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-core/src/settings.rs): `crates/hub-core/src/settings.rs`
- [Topic hub](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/hub.rs): `crates/hub-telegram/src/hub.rs`
- [Topic session](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/session.rs): `crates/hub-telegram/src/session.rs`

### Agent runtimes

- [Agent channel](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-agent/src/channel.rs): `crates/hub-agent/src/channel.rs`
- [Claude runtime](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-claude/src/session.rs): `crates/hub-claude/src/session.rs`
- [Codex runtime](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-codex/src/backend.rs): `crates/hub-codex/src/backend.rs`
- [Qwen runtime](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-qwen/src/session.rs): `crates/hub-qwen/src/session.rs`
- [Hermes runtime](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-hermes/src/backend.rs): `crates/hub-hermes/src/backend.rs`
- [OpenCode runtime](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-opencode/src/backend.rs): `crates/hub-opencode/src/backend.rs`

### Workflow capabilities

- [Progress reporting](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/progress.rs): `crates/hub-telegram/src/progress.rs`
- [Result delivery](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/results.rs): `crates/hub-telegram/src/results.rs`
- [History snapshots](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/snapshots.rs): `crates/hub-telegram/src/snapshots.rs`
- [Agent handoff](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/handoff.rs): `crates/hub-telegram/src/handoff.rs`
- [Retry outbox](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/outbox.rs): `crates/hub-telegram/src/outbox.rs`
- [Preset actions](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/actions.rs): `crates/hub-telegram/src/actions.rs`
- [Voice transcription](https://github.com/aprazdnikov/agent-hub-rs/blob/main/crates/hub-telegram/src/voice.rs): `crates/hub-telegram/src/voice.rs`

### Other components

- **Phone user**

## Connections

- Phone user → Telegram Bot API: sends task
- Settings window → Settings and projects: configures
- Settings window → Bot supervisor: controls (evidence: `crates/hub-app/src/gui/app.rs`)
- Bot supervisor → Topic hub: starts bot
- Telegram Bot API → Bot listener: delivers updates
- Bot listener → Update conversion: converts updates (evidence: `crates/hub-telegram/src/telegram.rs`)
- Bot listener → Topic hub: routes events (evidence: `crates/hub-telegram/src/telegram.rs`)
- Topic hub → Topic session: starts session (evidence: `crates/hub-telegram/src/hub.rs`)
- Topic session → Attachment download: downloads attachments (evidence: `crates/hub-telegram/src/session.rs`)
- Topic session → Agent channel: runs agent (evidence: `crates/hub-telegram/src/session.rs`)
- Agent channel → Claude runtime: dispatches
- Agent channel → Codex runtime: dispatches
- Agent channel → Qwen runtime: dispatches
- Agent channel → Hermes runtime: dispatches
- Agent channel → OpenCode runtime: dispatches
- Topic session → Progress reporting: reports events (evidence: `crates/hub-telegram/src/session.rs`)
- Topic session → Result delivery: relays results (evidence: `crates/hub-telegram/src/session.rs`)
- Topic hub → Delivery policy: sends responses (evidence: `crates/hub-telegram/src/hub.rs`)
- Delivery policy → Messenger API: applies policy (evidence: `crates/hub-telegram/src/sender.rs`)
- Messenger API → Telegram Bot API: sends messages
- Topic hub → History snapshots: saves history (evidence: `crates/hub-telegram/src/hub.rs`)
- Topic hub → Agent handoff: handles handoff (evidence: `crates/hub-telegram/src/hub.rs`)
- Topic hub → Retry outbox: manages delivery (evidence: `crates/hub-telegram/src/hub.rs`)
- Topic hub → Preset actions: runs commands (evidence: `crates/hub-telegram/src/hub.rs`)
- Topic hub → Voice transcription: handles voice (evidence: `crates/hub-telegram/src/hub.rs`)
- Settings and projects → Topic hub: configures workflow
