# ceelopez/bot-hq architecture

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

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

## Overview

Bot HQ is a browser-based workspace for a team of Hermes agents, each with its own identity, memory, and desktop on a shared Orgo computer. A user signs in, selects or creates a bot, chats or assigns work, and follows streamed progress; bots can use connected apps, computer screens, routines, tasks, Library files, and voice. The server coordinates bot execution, persistence, and integrations. Major capabilities are retained from the README; several internal relationships are omitted where the sampled source shows imports but not runtime calls.

Main entry points: [`web/src/App.tsx`](https://github.com/ceelopez/bot-hq/blob/main/web/src/App.tsx) (Bot HQ app), [`server/src/agent/tools.ts`](https://github.com/ceelopez/bot-hq/blob/main/server/src/agent/tools.ts) (Agent tools), [`server/src/routes.ts`](https://github.com/ceelopez/bot-hq/blob/main/server/src/routes.ts) (HTTP and SSE routes), [`server/src/computer.ts`](https://github.com/ceelopez/bot-hq/blob/main/server/src/computer.ts) (Computer and screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser workspace"]
  node_browser["Bot HQ app<br/>[App.tsx]"]
  node_clientstate["Client state<br/>[store.ts]"]
  node_chat["Chat and transcript<br/>[ChatView.tsx]"]
  node_viewer["Computer viewer<br/>[ComputerViewer.tsx]"]
  node_taskview["Tasks view<br/>[TasksView.tsx]"]
  node_voiceui["Voice interface<br/>[call.ts]"]
end

subgraph group_server["Server runtime"]
  node_routes["HTTP and SSE routes<br/>[routes.ts]"]
  node_roomroutes["Room routes<br/>[routes-rooms.ts]"]
  node_proactiveroutes["Proactive routes"]
  node_auth["Session auth<br/>[auth.ts]"]
  node_engine["Hermes gateway manager<br/>[engine.ts]"]
end

subgraph group_agents["Agent capabilities"]
  node_loop["Agent turn loop<br/>[loop.ts]"]
  node_rooms["Bot rooms and messages<br/>[rooms.ts]"]
  node_tools["Agent tools<br/>[tools.ts]"]
  node_mcp["MCP server<br/>[mcp.ts]"]
  node_routines["Routines and scheduling<br/>[routines.ts]"]
  node_proactive["Proactive work<br/>[proactive.ts]"]
  node_voice["Voice service<br/>[voice.ts]"]
  node_composio["Connected apps<br/>[composio.ts]"]
end

subgraph group_state["Persistence and state"]
  node_db[("SQLite database<br/>[db.ts]")]
  node_store["Bot and transcript state<br/>[store.ts]"]
  node_memory["Bot memory files<br/>[engine-memory.ts]"]
end

subgraph group_computer["Computer environment"]
  node_computer["Computer and screens<br/>[computer.ts]"]
  node_desk["Desktop management<br/>[desk.ts]"]
  node_box["Screen setup<br/>[box.ts]"]
  node_desklib["Desktop helpers<br/>[hqlib.py]"]
end

node_user(("User"))
node_hermes["Hermes gateway"]
node_orgo["Orgo"]
node_composio_service["Composio service"]
node_xai["xAI"]

node_user -->|"uses"| node_browser
node_browser -->|"updates"| node_clientstate
node_browser -->|"renders"| node_chat
node_browser -->|"renders"| node_viewer
node_browser -->|"renders"| node_taskview
node_browser -->|"HTTP and SSE"| node_routes
node_browser -->|"VNC WebSocket"| node_computer
node_browser -.->|"voice requests"| node_voice
node_routes -.->|"authenticates"| node_auth
node_routes -.->|"starts turns"| node_loop
node_routes -->|"dispatches turns"| node_engine
node_routes -.->|"reads and writes"| node_store
node_roomroutes -.->|"handles rooms"| node_rooms
node_proactiveroutes -.->|"handles requests"| node_proactive
node_engine -->|"POST responses"| node_hermes
node_hermes -->|"calls tools"| node_mcp
node_mcp -.->|"dispatches tools"| node_tools
node_tools -.->|"messages bots"| node_rooms
node_tools -.->|"uses connected apps"| node_composio
node_composio -->|"connects apps"| node_composio_service
node_tools -.->|"manages routines"| node_routines
node_tools -.->|"uses proactive work"| node_proactive
node_tools -->|"searches X"| node_xai
node_voice -->|"realtime voice"| node_xai
node_voiceui -->|"voice modes"| node_xai
node_voiceui -->|"hands off work"| node_voice
node_routines -.->|"persists schedules"| node_store
node_store -->|"reads and writes"| node_db
node_auth -->|"stores sessions"| node_db
node_engine -->|"gets screen details"| node_computer
node_engine -->|"uses Hermes home"| node_memory
node_computer -->|"manages screens"| node_orgo
node_computer -.->|"coordinates desktop"| node_desk
node_computer -.->|"sets up screens"| node_box
node_desk -->|"uses helpers"| node_desklib
node_box -->|"uses helpers"| node_desklib

click node_browser "https://github.com/ceelopez/bot-hq/blob/main/web/src/App.tsx"
click node_clientstate "https://github.com/ceelopez/bot-hq/blob/main/web/src/store.ts"
click node_chat "https://github.com/ceelopez/bot-hq/blob/main/web/src/components/ChatView.tsx"
click node_viewer "https://github.com/ceelopez/bot-hq/blob/main/web/src/components/ComputerViewer.tsx"
click node_taskview "https://github.com/ceelopez/bot-hq/blob/main/web/src/components/config/TasksView.tsx"
click node_voiceui "https://github.com/ceelopez/bot-hq/blob/main/web/src/voice/call.ts"
click node_routes "https://github.com/ceelopez/bot-hq/blob/main/server/src/routes.ts"
click node_roomroutes "https://github.com/ceelopez/bot-hq/blob/main/server/src/routes-rooms.ts"
click node_proactiveroutes "https://github.com/ceelopez/bot-hq/blob/main/server/src/routes-proactive.ts"
click node_auth "https://github.com/ceelopez/bot-hq/blob/main/server/src/lib/auth.ts"
click node_engine "https://github.com/ceelopez/bot-hq/blob/main/server/src/engine.ts"
click node_loop "https://github.com/ceelopez/bot-hq/blob/main/server/src/agent/loop.ts"
click node_rooms "https://github.com/ceelopez/bot-hq/blob/main/server/src/agent/rooms.ts"
click node_tools "https://github.com/ceelopez/bot-hq/blob/main/server/src/agent/tools.ts"
click node_mcp "https://github.com/ceelopez/bot-hq/blob/main/server/src/mcp.ts"
click node_routines "https://github.com/ceelopez/bot-hq/blob/main/server/src/routines.ts"
click node_proactive "https://github.com/ceelopez/bot-hq/blob/main/server/src/proactive.ts"
click node_voice "https://github.com/ceelopez/bot-hq/blob/main/server/src/voice.ts"
click node_composio "https://github.com/ceelopez/bot-hq/blob/main/server/src/composio.ts"
click node_db "https://github.com/ceelopez/bot-hq/blob/main/server/src/db.ts"
click node_store "https://github.com/ceelopez/bot-hq/blob/main/server/src/store.ts"
click node_memory "https://github.com/ceelopez/bot-hq/blob/main/server/src/engine-memory.ts"
click node_computer "https://github.com/ceelopez/bot-hq/blob/main/server/src/computer.ts"
click node_desk "https://github.com/ceelopez/bot-hq/blob/main/server/src/desk.ts"
click node_box "https://github.com/ceelopez/bot-hq/blob/main/server/src/box.ts"
click node_desklib "https://github.com/ceelopez/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_clientstate,node_chat,node_viewer,node_taskview,node_voiceui,node_user toneBlue
class node_routes,node_roomroutes,node_proactiveroutes,node_auth,node_engine toneAmber
class node_loop,node_rooms,node_tools,node_mcp,node_routines,node_proactive,node_voice,node_composio toneMint
class node_db,node_store,node_memory toneRose
class node_computer,node_desk,node_box,node_desklib,node_hermes,node_orgo,node_composio_service,node_xai toneIndigo
```

## Components

### Browser workspace

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

### Server runtime

- [HTTP and SSE routes](https://github.com/ceelopez/bot-hq/blob/main/server/src/routes.ts): `server/src/routes.ts`
- [Room routes](https://github.com/ceelopez/bot-hq/blob/main/server/src/routes-rooms.ts): `server/src/routes-rooms.ts`
- [Proactive routes](https://github.com/ceelopez/bot-hq/blob/main/server/src/routes-proactive.ts): `server/src/routes-proactive.ts`
- [Session auth](https://github.com/ceelopez/bot-hq/blob/main/server/src/lib/auth.ts): `server/src/lib/auth.ts`
- [Hermes gateway manager](https://github.com/ceelopez/bot-hq/blob/main/server/src/engine.ts): `server/src/engine.ts`

### Agent capabilities

- [Agent turn loop](https://github.com/ceelopez/bot-hq/blob/main/server/src/agent/loop.ts): `server/src/agent/loop.ts`
- [Bot rooms and messages](https://github.com/ceelopez/bot-hq/blob/main/server/src/agent/rooms.ts): `server/src/agent/rooms.ts`
- [Agent tools](https://github.com/ceelopez/bot-hq/blob/main/server/src/agent/tools.ts): `server/src/agent/tools.ts`
- [MCP server](https://github.com/ceelopez/bot-hq/blob/main/server/src/mcp.ts): `server/src/mcp.ts`
- [Routines and scheduling](https://github.com/ceelopez/bot-hq/blob/main/server/src/routines.ts): `server/src/routines.ts`
- [Proactive work](https://github.com/ceelopez/bot-hq/blob/main/server/src/proactive.ts): `server/src/proactive.ts`
- [Voice service](https://github.com/ceelopez/bot-hq/blob/main/server/src/voice.ts): `server/src/voice.ts`
- [Connected apps](https://github.com/ceelopez/bot-hq/blob/main/server/src/composio.ts): `server/src/composio.ts`

### Persistence and state

- [SQLite database](https://github.com/ceelopez/bot-hq/blob/main/server/src/db.ts): `server/src/db.ts`
- [Bot and transcript state](https://github.com/ceelopez/bot-hq/blob/main/server/src/store.ts): `server/src/store.ts`
- [Bot memory files](https://github.com/ceelopez/bot-hq/blob/main/server/src/engine-memory.ts): `server/src/engine-memory.ts`

### Computer environment

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

### Other components

- **User**
- **Hermes gateway**
- **Orgo**
- **Composio service**
- **xAI**

## Connections

- User → Bot HQ app: uses (evidence: `README.md`)
- Bot HQ app → Client state: updates (evidence: `web/src/App.tsx`)
- Bot HQ app → Chat and transcript: renders (evidence: `web/src/App.tsx`)
- Bot HQ app → Computer viewer: renders (evidence: `web/src/App.tsx`)
- Bot HQ app → Tasks view: renders (evidence: `web/src/App.tsx`)
- Bot HQ app → HTTP and SSE routes: HTTP and SSE (evidence: `README.md`)
- Bot HQ app → Computer and screens: VNC WebSocket (evidence: `README.md`)
- Bot HQ app → Voice service: voice requests
- HTTP and SSE routes → Session auth: authenticates (evidence: `server/src/routes.ts`)
- HTTP and SSE routes → Agent turn loop: starts turns (evidence: `server/src/routes.ts`)
- HTTP and SSE routes → Hermes gateway manager: dispatches turns (evidence: `README.md`)
- HTTP and SSE routes → Bot and transcript state: reads and writes (evidence: `server/src/routes.ts`)
- Room routes → Bot rooms and messages: handles rooms (evidence: `server/src/routes-rooms.ts`)
- Proactive routes → Proactive work: handles requests (evidence: `server/src/routes-proactive.ts`)
- Hermes gateway manager → Hermes gateway: POST responses (evidence: `README.md`)
- Hermes gateway → MCP server: calls tools (evidence: `README.md`)
- MCP server → Agent tools: dispatches tools
- Agent tools → Bot rooms and messages: messages bots (evidence: `server/src/agent/tools.ts`)
- Agent tools → Connected apps: uses connected apps (evidence: `server/src/agent/tools.ts`)
- Connected apps → Composio service: connects apps (evidence: `README.md`)
- Agent tools → Routines and scheduling: manages routines (evidence: `server/src/agent/tools.ts`)
- Agent tools → Proactive work: uses proactive work (evidence: `server/src/agent/tools.ts`)
- Agent tools → xAI: searches X (evidence: `README.md`)
- Voice service → xAI: realtime voice (evidence: `README.md`)
- Voice interface → xAI: voice modes (evidence: `README.md`)
- Voice interface → Voice service: hands off work (evidence: `README.md`)
- Routines and scheduling → Bot and transcript state: persists schedules (evidence: `server/src/routines.ts`)
- Bot and transcript state → SQLite database: reads and writes (evidence: `server/src/store.ts`)
- Session auth → SQLite database: stores sessions (evidence: `server/src/lib/auth.ts`)
- Hermes gateway manager → Computer and screens: gets screen details (evidence: `server/src/engine.ts`)
- Hermes gateway manager → Bot memory files: uses Hermes home (evidence: `server/src/engine-memory.ts`)
- Computer and screens → Orgo: manages screens (evidence: `README.md`)
- Computer and screens → Desktop management: coordinates desktop (evidence: `server/src/computer.ts`)
- Computer and screens → Screen setup: sets up screens (evidence: `server/src/computer.ts`)
- Desktop management → Desktop helpers: uses helpers (evidence: `server/box/hqlib.py`)
- Screen setup → Desktop helpers: uses helpers (evidence: `server/box/hqlib.py`)