Architecture
Understanding SeaClip's hub-spoke architecture and data flow
System Overview
┌─────────────────────────────────────────────────────────────────┐
│ SeaClip Hub │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ React Dashboard │ │ Express API │ │ WebSocket Hub │ │
│ │ (Vite + Tailwind)│ │ (REST + Auth) │ │ (Real-time) │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ │ │
│ ┌─────────────────────────────┴─────────────────────────────┐ │
│ │ Service Layer │ │
│ │ AgentService · DeviceService · IssueService · CostService │ │
│ └─────────────────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────┴─────────────────────────────┐ │
│ │ Adapter Layer │ │
│ │ SeaClaw · Ollama · AgentZero · Telegram · Process · HTTP │ │
│ └─────────────────────────────┬─────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────┴─────────────────────────────┐ │
│ │ Data Layer │ │
│ │ PostgreSQL (Drizzle ORM) │ SpacetimeDB (Real-time) │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│ │ │
┌─────┴─────┐ ┌────┴────┐ ┌─────┴─────┐
│ Raspberry │ │ Jetson │ │ Laptop │
│ Pi │ │ Orin │ │ (Linux) │
│ Spoke │ │ Spoke │ │ Spoke │
└───────────┘ └─────────┘ └───────────┘
Technology Stack
| Layer | Technology | Package |
|---|---|---|
| Dashboard | React 18, Vite, TailwindCSS, shadcn/ui | @seaclip/ui |
| API Server | Node.js, Express, tsx | @seaclip/server |
| Real-time | WebSocket (ws), SpacetimeDB | @seaclip/server |
| ORM | Drizzle ORM | @seaclip/server |
| Database | PostgreSQL 17 (prod), SQLite (dev) | — |
| AI Runtime | Ollama, Agent Zero | adapter layer |
| CLI | Commander.js, Inquirer, Ora | @seaclip/cli |
| Monorepo | pnpm workspaces, Turborepo | root |
Hub vs Spoke
Hub (Central Server)
- Runs the dashboard UI
- Hosts the REST API
- Stores all data (PostgreSQL)
- Dispatches tasks to agents
- Monitors device health
- Handles authentication
Spoke (Edge Device)
- Runs AI agents locally
- Sends telemetry to hub
- Receives task assignments
- Executes LLM inference
- Reports results back
- Lightweight footprint
Request Flow: Heartbeat Lifecycle
A heartbeat run is the fundamental unit of agent activity:
Agent (spoke) Hub (server) Database
│ │ │
│ 1. GET /api/companies/:c/ │ │
│ agents/:a │ │
│ ──────────────────────────────► │ │
│ │ SELECT agent WHERE id=:a │
│ │ ───────────────────────────────►│
│ ◄────────────────────────────── │ ◄───────────────────────────────│
│ agent config + instructions │ │
│ │ │
│ 2. GET /api/companies/:c/ │ │
│ issues?assigneeAgentId=:a │ │
│ ──────────────────────────────► │ │
│ ◄────────────────────────────── │ │
│ [list of todo issues] │ │
│ │ │
│ 3. POST /issues/:id/checkout │ │
│ ──────────────────────────────► │ UPDATE status=in_progress │
│ ◄────────────────────────────── │ ───────────────────────────────►│
│ run_id + issue detail │ │
│ │ │
│ [agent does the work] │ │
│ │ │
│ 4. PATCH /issues/:id │ │
│ { status: "done" } │ │
│ ──────────────────────────────► │ UPDATE issue │
│ ◄────────────────────────────── │ INSERT heartbeat_run │
│ updated issue │ ───────────────────────────────►│
Database Schema
Core Tables
| Table | Description |
|---|---|
companies |
Top-level tenant / workspace |
agents |
AI agents, one per logical worker |
agent_configs |
Per-agent adapter configuration (JSON) |
issues |
Tasks / work items |
heartbeat_runs |
Audit log of agent invocations |
cost_entries |
Token + compute cost records |
devices |
Registered edge devices (spokes) |
device_telemetry |
Time-series telemetry snapshots |
Entity Relationships
companies (1) ──── (N) agents
companies (1) ──── (N) issues
companies (1) ──── (N) devices
agents (1) ──── (N) issues [assignee]
agents (1) ──── (N) heartbeat_runs
heartbeat_runs (1) ── (N) cost_entries
devices (1) ──── (N) device_telemetry
Adapter Model
Adapters are pluggable drivers that communicate with different AI backends:
typescript
interface AgentAdapter {
// Invoke the agent — send a task
invoke(params: InvokeParams): Promise<InvokeResult>;
// Check if agent is reachable
ping(): Promise<PingResult>;
// Optional: stream output in real time
stream?(params: InvokeParams): AsyncIterable<string>;
}Available Adapters
| Adapter | Description |
|---|---|
seaclaw |
SSH + REST to SeaClaw edge nodes |
ollama |
HTTP to Ollama API with GPU tracking |
agent_zero |
Agent Zero sessions with memory sync |
telegram |
Telegram bot interface |
process |
Local CLI command execution |
http |
Generic webhook adapter |
WebSocket Events
Real-time events broadcast to connected clients:
| Event | Payload | Trigger |
|---|---|---|
issue:created |
Issue object | New issue inserted |
issue:updated |
Issue object | Status or field change |
agent:heartbeat |
{ agentId, status, runId } |
Heartbeat run completes |
device:telemetry |
Telemetry snapshot | Device posts telemetry |
device:status |
{ deviceId, status } |
Device online/offline |
Repository Structure
text
seaclip/
├── cli/ CLI tool (@seaclip/cli)
│ └── src/
│ ├── commands/ One file per command
│ ├── config/ Config read/write
│ └── checks/ Health check functions
├── server/ Express API (@seaclip/server)
│ └── src/
│ ├── db/ Drizzle schema + migrations
│ ├── routes/ Express routers
│ ├── services/ Business logic
│ ├── adapters/ Adapter implementations
│ └── ws/ WebSocket hub
├── ui/ React dashboard (@seaclip/ui)
│ └── src/
│ ├── pages/ Route-based pages
│ ├── components/ Shared UI components
│ └── lib/ API client, utilities
├── shared/ Shared types (@seaclip/shared)
├── spacetimedb/ SpacetimeDB module (Rust)
├── doc/ Extended documentation
├── docs/ HTML documentation (this site)
└── scripts/ Dev and ops scripts