Control-Center/docs/CONTEXT.md

Control Center — Project Context

Last updated: 2026-05-21 Repo: CubeCraft-Creations/Control-Center | Host: code.cubecraftcreations.com Local clone: /mnt/ai-storage/projects/Control-Center | Default branch: dev Discord: DISCORD_DEV_CONTROL_CENTER_CHANNEL_ID Linear Epic: CUB-119

---

Overview

Real-time dashboard for monitoring and controlling the OpenClaw agent fleet. Displays agent statuses, active tasks, sessions, and projects. Uses SSE for live updates from the Go backend, which connects to the OpenClaw gateway via WebSocket for live agent data.

Completed refactor: ASP.NET Core + Angular → Go + React is done (CUB-119 epic). All legacy code is removed from git.

Tech Stack

Layer	Technology	Notes
Backend	Go 1.24+	Chi router, pgx (PostgreSQL), SSE broker, gorilla/websocket
Frontend	React 18 + TypeScript	Vite, Tailwind CSS, React Query, TanStack Router
Database	PostgreSQL 16+	snake_case naming, 2 migrations
Real-time	SSE + WebSocket	SSE for browser, WebSocket for OpenClaw gateway
Gateway Integration	WebSocket client	OpenClaw gateway /ws — live agent + session RPC
API Client	TypeScript SDK	api-client/ — shared models, WS client, HTTP client
CI/CD	Gitea Actions	.gitea/workflows/dev.yml, deploy-dev.yaml
Deployment	Docker Compose	PostgreSQL + Go backend + React/nginx
Testing	Vitest, Go test	Unit + integration tests for WS client, gateway, handlers
Design	Kiosk layout	Bottom nav (mobile), nav rail (desktop), quick-jump drawer

Architecture

OpenClaw Gateway (WebSocket)
      │
      ▼
Go Backend (Chi + pgx)
 ├── Gateway WS Client (connect, reconnect, agents.list, sessions.list RPC)
 ├── SSE Broker (fan-out: agent.status, agent.task, fleet.update)
 ├── REST API (/api/agents, /api/sessions, /api/tasks, /api/projects)
 └── Repository/Store layers → PostgreSQL
      │
      ├── SSE /api/events
      ▼
React Frontend
 ├── SSEProvider → useRealtimeSync → React Query cache
 ├── HubPage (dashboard), LogsPage, ProjectsPage, SessionsPage, SettingsPage
 └── Layout (header bar + nav rail + bottom nav + quick-jump drawer)

Key Architecture Decisions

1. Go replaced ASP.NET Core — lighter runtime, faster cold-start, better concurrency for gateway polling
2. React replaced Angular — lighter than Angular for dashboard/kiosk use
3. SSE over SignalR — simpler server-side, unidirectional events sufficient for browser updates
4. WebSocket for gateway integration — bidirectional needed for RPC (agents.list, sessions.list)
5. PostgreSQL — shared with Extrudex pattern; migrations in go-backend/migrations/
6. Agent state seeded on first boot via gateway.SeedDemoAgents for offline dev

Project Structure

Control-Center/
├── go-backend/                       # Go backend
│   ├── cmd/server/main.go            # Entrypoint, wire deps, start gateway poller
│   ├── Dockerfile / go.mod / go.sum
│   ├── migrations/                   # 001_initial_schema, 002_add_indexes
│   └── internal/
│       ├── config/config.go          # Env vars (DATABASE_URL, GATEWAY_URL, etc.)
│       ├── db/db.go                  # PostgreSQL pool (pgx)
│       ├── gateway/
│       │   ├── client.go             # GW poller → sync DB + SSE fan-out
│       │   ├── events.go             # SSE event broker
│       │   ├── events_test.go
│       │   ├── sync.go               # Initial sync from gateway
│       │   ├── sync_test.go
│       │   ├── wsclient.go           # WebSocket client (handshake, connect, reconnect, RPC)
│       │   └── wsclient_test.go
│       ├── handler/
│       │   ├── agent.go              # CRUD + history
│       │   ├── project.go            # List projects
│       │   ├── session.go            # List sessions
│       │   ├── sse.go                # SSE broker: subscribe + broadcast
│       │   ├── task.go               # List tasks
│       │   ├── helpers.go
│       │   ├── handler_test.go
│       │   └── mock_repos_test.go
│       ├── models/models.go          # Domain types
│       ├── repository/               # DB access layer + interfaces
│       ├── router/router.go          # Chi router: REST + SSE mount
│       └── store/                    # Agent, Project, Session, Task stores
├── api-client/                       # Shared TypeScript SDK
│   └── src/
│       ├── models/types.ts           # Agent, Session, Task, Project, SSE event types
│       ├── services/http-client.ts   # Axios REST client
│       ├── utils/
│       │   ├── config.ts             # Client config
│       │   └── status-mapper.ts      # Agent status → display mapping
│       └── websocket/
│           └── ws-client.ts          # WebSocket client (handshake, Send, RPC, reconnector)
├── frontend/                         # React frontend
│   ├── Dockerfile + nginx.conf
│   ├── package.json + vite.config.ts
│   ├── src/
│   │   ├── App.tsx / main.tsx
│   │   ├── components/
│   │   │   ├── ErrorBoundary.tsx
│   │   │   └── Layout.tsx            # Header bar + nav rail + bottom nav + quick-jump
│   │   ├── contexts/
│   │   │   └── SSEContext.tsx         # SSEProvider — wraps entire app
│   │   ├── hooks/
│   │   │   ├── useLocalStorage.ts
│   │   │   ├── useRealtimeSync.ts     # SSE messages → React Query cache
│   │   │   ├── useRealtimeSync.test.tsx
│   │   │   ├── useSSE.ts              # SSE: connect, reconnect, typed events
│   │   │   ├── useSSE.test.ts
│   │   │   └── useTheme.tsx
│   │   ├── pages/
│   │   │   ├── HubPage.tsx            # Fleet dashboard (agent grid + stats)
│   │   │   ├── LogsPage.tsx           # Agent log viewer
│   │   │   ├── ProjectsPage.tsx       # Project list
│   │   │   ├── SessionsPage.tsx       # Session list
│   │   │   └── SettingsPage.tsx       # Settings + theme toggle
│   │   ├── services/
│   │   │   ├── api.ts                 # Axios REST client
│   │   │   └── sse.ts                 # SSE utilities
│   │   └── types/index.ts
│   └── vitest.config.ts
├── frontend-legacy/                  # Original Angular frontend (kept for reference, not in git)
├── backend/                          # Original ASP.NET backend (kept for reference, not in git)
│   ├── ControlCenter/                # ASP.NET Core project
│   └── Api/                          # API layer
├── design/
│   ├── command-hub-spec.md           # Detailed design spec
│   └── mockups/                      # Desktop kiosk, mobile, quick-jump drawer
├── kiosk/
│   ├── control-center-kiosk.service  # Systemd service
│   └── start-kiosk.sh                # Kiosk startup script
├── reference/
│   └── CONTROL_CENTER_CONTEXT.md     # Older context file (superseded by this one)
├── ci-image/Dockerfile               # CI build image
├── docker-compose.yml
└── .env.example

Database Schema (PostgreSQL)

agents

Column	Type	Notes
id	UUID PK
display_name	VARCHAR(256) NOT NULL
role	VARCHAR(256)
status	VARCHAR(32)	active, idle, thinking, error
current_task	VARCHAR(512)
task_progress	INTEGER DEFAULT 0
session_key	VARCHAR(256)
channel	VARCHAR(256)
last_activity	TIMESTAMP
error_message	TEXT
created_at	TIMESTAMP
updated_at	TIMESTAMP

sessions

Column	Type
id	UUID PK
session_key	VARCHAR(256) UNIQUE
agent_id	UUID FK → agents
channel	VARCHAR(256)
status	VARCHAR(32)
context_tokens	INTEGER
total_tokens	INTEGER
estimated_cost	NUMERIC
model	VARCHAR(256)
started_at	TIMESTAMP
last_activity_at	TIMESTAMP

tasks

Column	Type
id	UUID PK
agent_id	UUID FK → agents
title	VARCHAR(512)
description	TEXT
status	VARCHAR(32)
progress	INTEGER DEFAULT 0
session_key	VARCHAR(256)
created_at, updated_at	TIMESTAMP

projects

Column	Type
id	UUID PK
name	VARCHAR(256) UNIQUE
description	TEXT
status	VARCHAR(32)
agent_ids	TEXT[]
created_at, updated_at	TIMESTAMP

API Endpoints

Method	Endpoint	Description
GET	/health	Health check (probes DB)
GET	/api/agents	List all agents
POST	/api/agents	Create agent
GET	/api/agents/:id	Get agent detail
PUT	/api/agents/:id	Update agent
DELETE	/api/agents/:id	Delete agent
GET	/api/agents/:id/history	Agent status history
GET	/api/sessions	List sessions
GET	/api/tasks	List tasks
GET	/api/projects	List projects
GET	/api/events	SSE event stream

SSE Events

Event Type	Payload
agent.status	Agent status change
agent.task	Agent current task updated
agent.progress	Task progress percentage
fleet.update	Full fleet snapshot
connected	Connection established

CI/CD Pipeline

dev.yml

• Lint + typecheck: Go vet + golangci-lint + tsc
• Test: Go test + vitest
• Build: Go build + npm build
• Docker: Build and push images
• Triggers: push to dev/main

deploy-dev.yaml

• Workflow dispatch
• SCP deploy script to dev host
• systemctl restart with rollback

Docker Compose

Service	Image/Build	Ports	Depends On
postgres	postgres:16-alpine	5432	—
backend	./go-backend/Dockerfile	8080	postgres (healthy)
frontend	./frontend/Dockerfile	3000	backend (healthy)

Linear Issue Map

CUB	Title	Status
119	Epic: Control Center Refactor — .NET → Go + React	Todo
120	PostgreSQL schema + migrations	Done
121	React pages wired to real API	Done
122	React frontend scaffold	Done
123	Gateway integration + SSE streaming	Done
124	Go backend scaffold	Done
125	Real-time SSE frontend	Done
126	Docker Compose deployment	Done
127	CRUD API endpoints	Done
200	Live WebSocket gateway client (CUB-200-207 sub-epic)	In Review
201	agents.list + sessions.list RPC and data mapping	In Review
202	Real-time event subscription + SSE fan-out	In Review
203	WS client scaffold — handshake, connect, reconnect loop	In Review
204	Config, wiring, and graceful fallback	In Review
205	Unit tests — gateway utility functions	In Review
206	Unit tests — WSClient handshake, Send/RPC, frame router, reconnect	In Review
207	Unit tests — event handlers and initial sync	In Review

Legacy Issues (Angular/ASP.NET — all Done)

CUB-19 through CUB-63: All 27 Control Center issues completed, including minion mapping, breakroom UI, dark mode theme, agent cards, quick-jump drawer, adaptive nav, SignalR hub, and status animations.

Known Limitations / Next Steps

1. Agent detail/history views are scaffolded but not fully implemented
2. 16-bit minion breakroom concept (CUB-59-63) was on Angular — needs React port if desired
3. .env must be created from .env.example with a valid GATEWAY_URL for live agent data
4. Docker containers not currently running — start with docker compose up --build -d

Default Agent Assignments

Area	Agent	Notes
Backend (Go API, Gateway WS, SSE)	Dex	gitea-dex MCP
Database (PostgreSQL schema)	Hex	gitea-hex MCP
Frontend (React, Tailwind)	Rex	gitea-rex MCP
Design (wireframes, UX)	Sketch

Getting Started

cd /mnt/ai-storage/projects/Control-Center
git checkout dev
git pull origin dev

# Docker Compose (recommended)
cp .env.example .env    # edit GATEWAY_URL first
docker compose up --build -d

# Manual
cd go-backend && go run cmd/server/main.go     # → :8080
cd frontend && npm install && npm run dev       # → :5173 (Vite proxy to :8080)