Architecture

This page describes the internal architecture of ServerBee for developers and operators who want to understand how the system works under the hood.

System Overview

+--------------------------------------------------+
|              ServerBee Dashboard                  |
|                                                   |
|  +---------------------------------------------+ |
|  | Frontend (React SPA, embedded via rust-embed)| |
|  | React 19, TanStack Router/Query             | |
|  | shadcn/ui, Tailwind CSS v4, Recharts        | |
|  +---------------------------------------------+ |
|  +---------------------------------------------+ |
|  | Server (Rust)                                | |
|  | Axum Router                                  | |
|  |  +-- REST API handlers                      | |
|  |  +-- WebSocket: Agent + Browser + Terminal   | |
|  |  +-- Static files (rust-embed)              | |
|  | Service Layer                                | |
|  |  +-- AgentManager (connections/state)        | |
|  |  +-- AlertService (rule evaluation)          | |
|  |  +-- RecordService (metrics/aggregation)     | |
|  |  +-- NotificationService (dispatch)          | |
|  | Entity Layer (sea-orm)                       | |
|  |  +-- SQLite                                  | |
|  +---------------------------------------------+ |
+--------------------------+-----------------------+
                           | WebSocket (JSON + Binary)
+--------------------------v-----------------------+
|              ServerBee Agent (Rust)               |
|  common crate (shared types/protocol)             |
|  +-- Collector (system metrics)                   |
|  +-- Reporter (WebSocket + reconnect)             |
|  +-- Pinger (ICMP/TCP/HTTP probes)                |
|  +-- TerminalManager (PTY sessions)               |
+---------------------------------------------------+

Component Roles

Server (crates/server)

The central hub that:

• Serves the web dashboard (React SPA embedded via rust-embed)
• Exposes REST API endpoints for CRUD operations
• Manages WebSocket connections from agents and browsers
• Stores all data in SQLite
• Runs background tasks (record writing, aggregation, cleanup, alerting, offline detection)
• Dispatches notifications

Agent (crates/agent)

A lightweight daemon that:

• Collects system metrics using the sysinfo crate
• Reports metrics to the server over WebSocket every N seconds
• Runs ping probes as instructed by the server
• Provides PTY terminal sessions for remote shell access
• Executes remote commands dispatched by the server
• Supports self-upgrade when instructed

Common (crates/common)

A shared library crate containing:

• Protocol definitions -- AgentMessage, ServerMessage, BrowserMessage enums
• Data types -- SystemInfo, SystemReport, GpuReport, PingResult, ServerStatus, etc.
• Constants -- Default ports, timeouts, retention periods, alert parameters

Frontend (apps/web)

A React 19 single-page application:

• Routing -- TanStack Router (file-based)
• Data fetching -- TanStack Query for REST, native WebSocket for real-time updates
• UI components -- shadcn/ui with the base-nova theme
• Styling -- Tailwind CSS v4
• Charts -- Recharts via shadcn Chart wrappers
• Build -- Vite 7

The built frontend is embedded into the server binary at compile time, so there is nothing to deploy separately.

Communication Protocol

All communication uses WebSocket with JSON-encoded messages. Terminal data uses base64 encoding within the JSON frames.

Agent to Server (AgentMessage)

Server to Agent (ServerMessage)

Server to Browser (BrowserMessage)

Database Design

ServerBee uses SQLite with 25 tables across 5 categories:

Authentication (4 tables)

Server Management (4 tables)

Monitoring Data (9 tables)

Alerting & Operations (6 tables)

All tables use UTC timestamps. IDs are UUIDs (string type) for most entities, and auto-incrementing integers for high-volume records.

Background Tasks

The server spawns six long-running background tasks:

Security Model

Authentication Layers

ServerBee supports three authentication mechanisms:

1. Session-based (browser) -- User logs in with username/password, receives a session cookie. Sessions have a configurable TTL (default 24 hours).
2. API Key (automation) -- Users can create named API keys for programmatic access. Keys are hashed with SHA-256 and stored with an 8-character prefix for identification.
3. Agent Token (agents) -- Each registered server has a unique token hashed with argon2. Agents authenticate by providing the raw token as a query parameter on the WebSocket connection.

Role-Based Access

Two roles exist:

OAuth

OAuth login is supported for GitHub, Google, and generic OIDC providers. The allow_registration flag controls whether new users are automatically created on first OAuth login.

Rate Limiting

Login and agent registration endpoints are rate-limited to prevent brute-force attacks (default: 5 login attempts, 3 registration attempts per window).

TOTP

Users can enable TOTP-based two-factor authentication for additional security.

Workspace Structure

ServerBee/
  crates/
    common/          # Shared types, protocol, constants
    server/          # Server binary (Axum, sea-orm, background tasks)
    agent/           # Agent binary (collector, reporter, terminal)
  apps/
    web/             # React frontend (Vite, TanStack, shadcn/ui)
    fumadocs/        # Documentation site
  docs/              # Design documents and plans
  Cargo.toml         # Workspace root

The project uses a Cargo workspace for the Rust crates. The frontend is a separate Bun/Node project under apps/web/.