# nickvasilescu/bot-hq architecture

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

- Interactive diagram: https://gitdiagram.com/nickvasilescu/bot-hq
- Repository: https://github.com/nickvasilescu/bot-hq

## Overview

Bot HQ lets a user manage a team of Hermes agents: configure a bot and its apps, send work in chat or by voice, and follow progress and computer activity. The browser talks to the server over HTTP/SSE and VNC; the server coordinates agent turns, persistence, tools, schedules, screens, and integrations. The README documents the major product branches and external services. Some server modules are unsampled, so their internal call paths are omitted where the excerpts and index do not establish them.

Main entry points: [`server/src/routes.ts`](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routes.ts) (HTTP and event routes), [`web/src/App.tsx`](https://github.com/nickvasilescu/bot-hq/blob/main/web/src/App.tsx) (Browser interface), [`server/src/agent/tools.ts`](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/agent/tools.ts) (Agent tools), [`server/src/engine.ts`](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/engine.ts) (Hermes gateway manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_browser["Browser interface<br/>[App.tsx]"]
  node_webstate["Client state<br/>[store.ts]"]
  node_chat["Chat and transcript<br/>[ChatView.tsx]"]
  node_tasksui["Tasks view<br/>[TasksView.tsx]"]
  node_viewer["Computer viewer<br/>[ComputerViewer.tsx]"]
  node_voiceui["Voice interface<br/>[call.ts]"]
end

subgraph group_server["Server orchestration"]
  node_api["HTTP and event routes<br/>[routes.ts]"]
  node_configroutes["Bot configuration routes<br/>[routes-config.ts]"]
  node_roomroutes["Room routes<br/>[routes-rooms.ts]"]
  node_auth["Session authentication<br/>[auth.ts]"]
  node_db[("SQLite state<br/>[db.ts]")]
  node_store["Bot and task state<br/>[store.ts]"]
  node_hub["SSE event hub<br/>[hub.ts]"]
end

subgraph group_agent["Agent capabilities"]
  node_engine["Hermes gateway manager<br/>[engine.ts]"]
  node_loop["Agent turn loop<br/>[loop.ts]"]
  node_tools["Agent tools<br/>[tools.ts]"]
  node_rooms["Bot messaging<br/>[rooms.ts]"]
  node_routines["Routines and triggers<br/>[routines.ts]"]
  node_memory["Hermes memory<br/>[engine-memory.ts]"]
end

subgraph group_computer["Computer runtime"]
  node_computer["Computer and screens<br/>[computer.ts]"]
  node_desk["Desktop control<br/>[desk.ts]"]
  node_screenstyle["Screen presentation<br/>[hqlib.py]"]
end

subgraph group_integrations["External services"]
  node_hermes["Hermes gateways"]
  node_orgo["Orgo"]
  node_composio["Composio apps"]
  node_xai["xAI voice and search"]
end

node_user(("User"))

node_user -->|"uses"| node_browser
node_browser -->|"loads state"| node_webstate
node_browser -->|"renders"| node_chat
node_browser -->|"renders"| node_tasksui
node_browser -->|"renders"| node_viewer
node_webstate -.->|"HTTP requests"| node_api
node_browser -->|"HTTP and SSE"| node_api
node_browser -->|"VNC connection"| node_computer
node_voiceui -.->|"voice requests"| node_api
node_api -->|"authenticates"| node_auth
node_configroutes -->|"authenticates"| node_auth
node_roomroutes -->|"authenticates"| node_auth
node_api -->|"starts turns"| node_loop
node_api -->|"routes turns"| node_engine
node_api -->|"manages routines"| node_routines
node_api -.->|"reads and writes"| node_store
node_configroutes -.->|"configures bots"| node_engine
node_roomroutes -.->|"manages rooms"| node_rooms
node_store -->|"persists state"| node_db
node_store -->|"emits events"| node_hub
node_rooms -->|"uses state"| node_store
node_rooms -->|"emits events"| node_hub
node_loop -.->|"invokes tools"| node_tools
node_tools -->|"connects apps"| node_composio
node_tools -->|"searches X"| node_xai
node_tools -->|"offers tasks"| node_routines
node_tools -->|"messages bots"| node_rooms
node_engine -->|"HTTP responses"| node_hermes
node_hermes -->|"MCP tools"| node_api
node_engine -->|"gets screen"| node_computer
node_computer -->|"manages screens"| node_orgo
node_computer -->|"controls desktop"| node_desk
node_computer -.->|"sets display"| node_screenstyle
node_engine -->|"provides bot home"| node_memory
node_routines -->|"uses persistence"| node_store
node_voiceui -->|"realtime voice"| node_xai

click node_browser "https://github.com/nickvasilescu/bot-hq/blob/main/web/src/App.tsx"
click node_webstate "https://github.com/nickvasilescu/bot-hq/blob/main/web/src/store.ts"
click node_chat "https://github.com/nickvasilescu/bot-hq/blob/main/web/src/components/ChatView.tsx"
click node_tasksui "https://github.com/nickvasilescu/bot-hq/blob/main/web/src/components/config/TasksView.tsx"
click node_viewer "https://github.com/nickvasilescu/bot-hq/blob/main/web/src/components/ComputerViewer.tsx"
click node_voiceui "https://github.com/nickvasilescu/bot-hq/blob/main/web/src/voice/call.ts"
click node_api "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routes.ts"
click node_configroutes "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routes-config.ts"
click node_roomroutes "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routes-rooms.ts"
click node_auth "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/lib/auth.ts"
click node_db "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/db.ts"
click node_store "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/store.ts"
click node_hub "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/lib/hub.ts"
click node_engine "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/engine.ts"
click node_loop "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/agent/loop.ts"
click node_tools "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/agent/tools.ts"
click node_rooms "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/agent/rooms.ts"
click node_routines "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routines.ts"
click node_memory "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/engine-memory.ts"
click node_computer "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/computer.ts"
click node_desk "https://github.com/nickvasilescu/bot-hq/blob/main/server/src/desk.ts"
click node_screenstyle "https://github.com/nickvasilescu/bot-hq/blob/main/server/box/hqlib.py"

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_browser,node_webstate,node_chat,node_tasksui,node_viewer,node_voiceui,node_user toneBlue
class node_api,node_configroutes,node_roomroutes,node_auth,node_db,node_store,node_hub toneAmber
class node_engine,node_loop,node_tools,node_rooms,node_routines,node_memory toneMint
class node_computer,node_desk,node_screenstyle toneRose
class node_hermes,node_orgo,node_composio,node_xai toneIndigo
```

## Components

### Web app

- [Browser interface](https://github.com/nickvasilescu/bot-hq/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Client state](https://github.com/nickvasilescu/bot-hq/blob/main/web/src/store.ts): `web/src/store.ts`
- [Chat and transcript](https://github.com/nickvasilescu/bot-hq/blob/main/web/src/components/ChatView.tsx): `web/src/components/ChatView.tsx`
- [Tasks view](https://github.com/nickvasilescu/bot-hq/blob/main/web/src/components/config/TasksView.tsx): `web/src/components/config/TasksView.tsx`
- [Computer viewer](https://github.com/nickvasilescu/bot-hq/blob/main/web/src/components/ComputerViewer.tsx): `web/src/components/ComputerViewer.tsx`
- [Voice interface](https://github.com/nickvasilescu/bot-hq/blob/main/web/src/voice/call.ts): `web/src/voice/call.ts`

### Server orchestration

- [HTTP and event routes](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routes.ts): `server/src/routes.ts`
- [Bot configuration routes](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routes-config.ts): `server/src/routes-config.ts`
- [Room routes](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routes-rooms.ts): `server/src/routes-rooms.ts`
- [Session authentication](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/lib/auth.ts): `server/src/lib/auth.ts`
- [SQLite state](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/db.ts): `server/src/db.ts`
- [Bot and task state](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/store.ts): `server/src/store.ts`
- [SSE event hub](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/lib/hub.ts): `server/src/lib/hub.ts`

### Agent capabilities

- [Hermes gateway manager](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/engine.ts): `server/src/engine.ts`
- [Agent turn loop](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/agent/loop.ts): `server/src/agent/loop.ts`
- [Agent tools](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/agent/tools.ts): `server/src/agent/tools.ts`
- [Bot messaging](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/agent/rooms.ts): `server/src/agent/rooms.ts`
- [Routines and triggers](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/routines.ts): `server/src/routines.ts`
- [Hermes memory](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/engine-memory.ts): `server/src/engine-memory.ts`

### Computer runtime

- [Computer and screens](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/computer.ts): `server/src/computer.ts`
- [Desktop control](https://github.com/nickvasilescu/bot-hq/blob/main/server/src/desk.ts): `server/src/desk.ts`
- [Screen presentation](https://github.com/nickvasilescu/bot-hq/blob/main/server/box/hqlib.py): `server/box/hqlib.py`

### External services

- **Hermes gateways**
- **Orgo**
- **Composio apps**
- **xAI voice and search**

### Other components

- **User**

## Connections

- User → Browser interface: uses (evidence: `README.md`)
- Browser interface → Client state: loads state (evidence: `web/src/App.tsx`)
- Browser interface → Chat and transcript: renders (evidence: `web/src/App.tsx`)
- Browser interface → Tasks view: renders (evidence: `web/src/App.tsx`)
- Browser interface → Computer viewer: renders (evidence: `web/src/App.tsx`)
- Client state → HTTP and event routes: HTTP requests
- Browser interface → HTTP and event routes: HTTP and SSE (evidence: `README.md`)
- Browser interface → Computer and screens: VNC connection (evidence: `README.md`)
- Voice interface → HTTP and event routes: voice requests
- HTTP and event routes → Session authentication: authenticates (evidence: `server/src/routes.ts`)
- Bot configuration routes → Session authentication: authenticates (evidence: `server/src/routes-config.ts`)
- Room routes → Session authentication: authenticates (evidence: `server/src/routes-rooms.ts`)
- HTTP and event routes → Agent turn loop: starts turns (evidence: `README.md`)
- HTTP and event routes → Hermes gateway manager: routes turns (evidence: `README.md`)
- HTTP and event routes → Routines and triggers: manages routines (evidence: `README.md`)
- HTTP and event routes → Bot and task state: reads and writes (evidence: `server/src/routes.ts`)
- Bot configuration routes → Hermes gateway manager: configures bots (evidence: `server/src/routes-config.ts`)
- Room routes → Bot messaging: manages rooms (evidence: `server/src/routes-rooms.ts`)
- Bot and task state → SQLite state: persists state (evidence: `server/src/store.ts`)
- Bot and task state → SSE event hub: emits events (evidence: `server/src/store.ts`)
- Bot messaging → Bot and task state: uses state (evidence: `server/src/agent/rooms.ts`)
- Bot messaging → SSE event hub: emits events (evidence: `server/src/agent/rooms.ts`)
- Agent turn loop → Agent tools: invokes tools
- Agent tools → Composio apps: connects apps (evidence: `README.md`)
- Agent tools → xAI voice and search: searches X (evidence: `README.md`)
- Agent tools → Routines and triggers: offers tasks (evidence: `README.md`)
- Agent tools → Bot messaging: messages bots (evidence: `README.md`)
- Hermes gateway manager → Hermes gateways: HTTP responses (evidence: `README.md`)
- Hermes gateways → HTTP and event routes: MCP tools (evidence: `README.md`)
- Hermes gateway manager → Computer and screens: gets screen (evidence: `server/src/engine.ts`)
- Computer and screens → Orgo: manages screens (evidence: `server/src/computer.ts`)
- Computer and screens → Desktop control: controls desktop (evidence: `server/src/computer.ts`)
- Computer and screens → Screen presentation: sets display
- Hermes gateway manager → Hermes memory: provides bot home (evidence: `server/src/engine-memory.ts`)
- Routines and triggers → Bot and task state: uses persistence (evidence: `server/src/routines.ts`)
- Voice interface → xAI voice and search: realtime voice (evidence: `README.md`)
