# henrygd/beszel architecture

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

- Interactive diagram: https://gitdiagram.com/henrygd/beszel
- Repository: https://github.com/henrygd/beszel

## Overview

Beszel pairs a per-host agent with a PocketBase-based hub and dashboard. The main workflow is agent collection of host, container, storage, and network-monitoring metrics; delivery to the hub over WebSocket or SSH; system management and persistence; then dashboard visualization and alerting. The README documents capabilities such as multi-user/OAuth, backups, and API access that are not fully evidenced in sampled source. Connections reflect explicit README statements or the SOURCE INDEX; unsampled subsystem wiring is not asserted.

Main entry points: [`internal/hub/systems/system_manager.go`](https://github.com/henrygd/beszel/blob/main/internal/hub/systems/system_manager.go) (System manager), [`internal/site/src/components/router.tsx`](https://github.com/henrygd/beszel/blob/main/internal/site/src/components/router.tsx) (Dashboard routes), [`internal/hub/server.go`](https://github.com/henrygd/beszel/blob/main/internal/hub/server.go) (Hub server), [`agent/connection_manager.go`](https://github.com/henrygd/beszel/blob/main/agent/connection_manager.go) (Agent connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Host agent"]
  node_agent_collect["Metric collection"]
  node_agent_pools["Storage pools<br/>[storage_pool.go]"]
  node_agent_link["Agent connection"]
  node_agent_ssh["SSH responder<br/>[server.go]"]
  node_agent_ws["WebSocket client<br/>[client.go]"]
  node_agent_netmon["Network monitoring<br/>[network_monitor.go]"]
end

subgraph group_hub["Hub services"]
  node_hub_entry["Hub server<br/>[server.go]"]
  node_hub_systems["System manager<br/>[system_manager.go]"]
  node_hub_ws["WebSocket requests<br/>[request_manager.go]"]
  node_hub_transport["Agent transport"]
  node_hub_api["API and access<br/>[api.go]"]
  node_hub_mcp["MCP tools"]
  node_network_entities["Network monitor data<br/>[monitor.go]"]
end

subgraph group_data["Persistence"]
  node_records["Record processing<br/>[records.go]"]
  node_database[("PocketBase store")]
end

subgraph group_web["Web dashboard"]
  node_frontend["Dashboard routes<br/>[router.tsx]"]
  node_system_state["System client state<br/>[systemsManager.ts]"]
  node_system_data["System data hook<br/>[use-system-data.ts]"]
  node_charts["Metric charts<br/>[chart-data.ts]"]
  node_pool_view["Pool charts and table"]
end

subgraph group_ops["Alerts and integrations"]
  node_alerts["Alert evaluation"]
  node_notifications["Notifications"]
end

node_operator(("Operator"))
node_external_services(("Notification services"))

node_operator -->|"uses dashboard"| node_frontend
node_frontend -.->|"routes systems"| node_system_state
node_frontend -.->|"loads dashboard"| node_hub_entry
node_agent_collect -->|"collects pools"| node_agent_pools
node_agent_link -->|"connects WebSocket"| node_agent_ws
node_agent_link -->|"starts fallback"| node_agent_ssh
node_agent_ws -.->|"exchanges requests"| node_hub_ws
node_agent_ssh -.->|"serves SSH"| node_hub_transport
node_agent_netmon -.->|"reports monitoring"| node_hub_systems
node_hub_entry -.->|"manages systems"| node_hub_systems
node_hub_systems -->|"dispatches requests"| node_hub_ws
node_hub_systems -.->|"reads records"| node_database
node_hub_systems -.->|"feeds metrics"| node_records
node_records -.->|"stores aggregates"| node_database
node_hub_api -.->|"serves API data"| node_database
node_hub_mcp -.->|"exposes tools"| node_hub_api
node_system_state -.->|"fetches system state"| node_hub_entry
node_system_data -->|"prepares chart data"| node_charts
node_system_data -.->|"supplies pool data"| node_pool_view
node_alerts -->|"sends notifications"| node_notifications
node_notifications -->|"delivers alerts"| node_external_services
node_hub_systems -.->|"evaluates system alerts"| node_alerts
node_hub_systems -->|"tracks monitors"| node_network_entities

click node_agent_collect "https://github.com/henrygd/beszel/tree/main/agent"
click node_agent_pools "https://github.com/henrygd/beszel/blob/main/agent/storage_pool.go"
click node_agent_link "https://github.com/henrygd/beszel/blob/main/agent/connection_manager.go"
click node_agent_ssh "https://github.com/henrygd/beszel/blob/main/agent/server.go"
click node_agent_ws "https://github.com/henrygd/beszel/blob/main/agent/client.go"
click node_agent_netmon "https://github.com/henrygd/beszel/blob/main/agent/network_monitor.go"
click node_hub_entry "https://github.com/henrygd/beszel/blob/main/internal/hub/server.go"
click node_hub_systems "https://github.com/henrygd/beszel/blob/main/internal/hub/systems/system_manager.go"
click node_hub_ws "https://github.com/henrygd/beszel/blob/main/internal/hub/ws/request_manager.go"
click node_hub_transport "https://github.com/henrygd/beszel/tree/main/internal/hub/transport"
click node_hub_api "https://github.com/henrygd/beszel/blob/main/internal/hub/api.go"
click node_hub_mcp "https://github.com/henrygd/beszel/tree/main/internal/hub/mcp"
click node_records "https://github.com/henrygd/beszel/blob/main/internal/records/records.go"
click node_frontend "https://github.com/henrygd/beszel/blob/main/internal/site/src/components/router.tsx"
click node_system_state "https://github.com/henrygd/beszel/blob/main/internal/site/src/lib/systemsManager.ts"
click node_system_data "https://github.com/henrygd/beszel/blob/main/internal/site/src/components/routes/system/use-system-data.ts"
click node_charts "https://github.com/henrygd/beszel/blob/main/internal/site/src/components/routes/system/chart-data.ts"
click node_pool_view "https://github.com/henrygd/beszel/blob/main/internal/site/src/components/routes/system/storage-pools-table.tsx"
click node_alerts "https://github.com/henrygd/beszel/tree/main/internal/alerts"
click node_notifications "https://github.com/henrygd/beszel/blob/main/internal/alerts/notification_client.go"
click node_network_entities "https://github.com/henrygd/beszel/blob/main/internal/entities/monitor/monitor.go"

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_agent_collect,node_agent_pools,node_agent_link,node_agent_ssh,node_agent_ws,node_agent_netmon toneBlue
class node_hub_entry,node_hub_systems,node_hub_ws,node_hub_transport,node_hub_api,node_hub_mcp,node_network_entities toneAmber
class node_records,node_database toneMint
class node_frontend,node_system_state,node_system_data,node_charts,node_pool_view toneRose
class node_alerts,node_notifications,node_operator,node_external_services toneIndigo
```

## Components

### Host agent

- [Metric collection](https://github.com/henrygd/beszel/tree/main/agent): `agent`
- [Storage pools](https://github.com/henrygd/beszel/blob/main/agent/storage_pool.go): `agent/storage_pool.go`
- [Agent connection](https://github.com/henrygd/beszel/blob/main/agent/connection_manager.go): `agent/connection_manager.go`
- [SSH responder](https://github.com/henrygd/beszel/blob/main/agent/server.go): `agent/server.go`
- [WebSocket client](https://github.com/henrygd/beszel/blob/main/agent/client.go): `agent/client.go`
- [Network monitoring](https://github.com/henrygd/beszel/blob/main/agent/network_monitor.go): `agent/network_monitor.go`

### Hub services

- [Hub server](https://github.com/henrygd/beszel/blob/main/internal/hub/server.go): `internal/hub/server.go`
- [System manager](https://github.com/henrygd/beszel/blob/main/internal/hub/systems/system_manager.go): `internal/hub/systems/system_manager.go`
- [WebSocket requests](https://github.com/henrygd/beszel/blob/main/internal/hub/ws/request_manager.go): `internal/hub/ws/request_manager.go`
- [Agent transport](https://github.com/henrygd/beszel/tree/main/internal/hub/transport): `internal/hub/transport`
- [API and access](https://github.com/henrygd/beszel/blob/main/internal/hub/api.go): `internal/hub/api.go`
- [MCP tools](https://github.com/henrygd/beszel/tree/main/internal/hub/mcp): `internal/hub/mcp`
- [Network monitor data](https://github.com/henrygd/beszel/blob/main/internal/entities/monitor/monitor.go): `internal/entities/monitor/monitor.go`

### Persistence

- [Record processing](https://github.com/henrygd/beszel/blob/main/internal/records/records.go): `internal/records/records.go`
- **PocketBase store**

### Web dashboard

- [Dashboard routes](https://github.com/henrygd/beszel/blob/main/internal/site/src/components/router.tsx): `internal/site/src/components/router.tsx`
- [System client state](https://github.com/henrygd/beszel/blob/main/internal/site/src/lib/systemsManager.ts): `internal/site/src/lib/systemsManager.ts`
- [System data hook](https://github.com/henrygd/beszel/blob/main/internal/site/src/components/routes/system/use-system-data.ts): `internal/site/src/components/routes/system/use-system-data.ts`
- [Metric charts](https://github.com/henrygd/beszel/blob/main/internal/site/src/components/routes/system/chart-data.ts): `internal/site/src/components/routes/system/chart-data.ts`
- [Pool charts and table](https://github.com/henrygd/beszel/blob/main/internal/site/src/components/routes/system/storage-pools-table.tsx): `internal/site/src/components/routes/system/storage-pools-table.tsx`

### Alerts and integrations

- [Alert evaluation](https://github.com/henrygd/beszel/tree/main/internal/alerts): `internal/alerts`
- [Notifications](https://github.com/henrygd/beszel/blob/main/internal/alerts/notification_client.go): `internal/alerts/notification_client.go`

### Other components

- **Operator**
- **Notification services**

## Connections

- Operator → Dashboard routes: uses dashboard
- Dashboard routes → System client state: routes systems
- Dashboard routes → Hub server: loads dashboard
- Metric collection → Storage pools: collects pools (evidence: `agent/storage_pool.go`)
- Agent connection → WebSocket client: connects WebSocket (evidence: `agent/connection_manager.go`)
- Agent connection → SSH responder: starts fallback (evidence: `agent/connection_manager.go`)
- WebSocket client → WebSocket requests: exchanges requests
- SSH responder → Agent transport: serves SSH
- Network monitoring → System manager: reports monitoring
- Hub server → System manager: manages systems
- System manager → WebSocket requests: dispatches requests (evidence: `internal/hub/systems/system_manager.go`)
- System manager → PocketBase store: reads records
- System manager → Record processing: feeds metrics
- Record processing → PocketBase store: stores aggregates
- API and access → PocketBase store: serves API data
- MCP tools → API and access: exposes tools
- System client state → Hub server: fetches system state
- System data hook → Metric charts: prepares chart data (evidence: `internal/site/src/components/routes/system/use-system-data.ts`)
- System data hook → Pool charts and table: supplies pool data
- Alert evaluation → Notifications: sends notifications (evidence: `internal/alerts/notification_client.go`)
- Notifications → Notification services: delivers alerts (evidence: `internal/alerts/notification_client.go`)
- System manager → Alert evaluation: evaluates system alerts
- System manager → Network monitor data: tracks monitors (evidence: `internal/hub/systems/system_manager.go`)
