From f3ce08497af40cda6bd81ca78ec6d8a5d424bb67 Mon Sep 17 00:00:00 2001 From: Otto the Minion Date: Thu, 21 May 2026 13:29:24 -0400 Subject: [PATCH] docs: add comprehensive project context file (CONTEXT.md) for agent reference --- docs/CONTEXT.md | 304 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 docs/CONTEXT.md diff --git a/docs/CONTEXT.md b/docs/CONTEXT.md new file mode 100644 index 0000000..abede78 --- /dev/null +++ b/docs/CONTEXT.md @@ -0,0 +1,304 @@ +# 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](https://linear.app/cubecraft-creations/issue/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 + +```bash +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) +```