224 lines
6.9 KiB
Markdown
224 lines
6.9 KiB
Markdown
# Control Center
|
||
|
||
> Real-time agent fleet dashboard for the OpenClaw AI development team.
|
||
|
||
Control Center monitors and controls the full CubeCraft Creations AI agent fleet — Otto, Rex, Dex, Hex, Pip, Nano, Sketch, Bob, Stuart, Norbert, and Flip. It provides live agent status, task progress, session logs, and a command interface, backed by SignalR for push-based updates directly from the OpenClaw gateway.
|
||
|
||
---
|
||
|
||
## Tech Stack
|
||
|
||
| Layer | Technology |
|
||
|---|---|
|
||
| Backend | ASP.NET Core Web API (.NET 8) |
|
||
| Database | PostgreSQL (snake_case via EF Core) |
|
||
| ORM | Entity Framework Core |
|
||
| Real-time | SignalR (`AgentStatusHub`) |
|
||
| Frontend | Angular (latest), Angular Material, Angular Signals |
|
||
| API Client | TypeScript package (`api-client/`) |
|
||
| Deployment | Docker |
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
Control-Center/
|
||
├── backend/
|
||
│ ├── ControlCenter/
|
||
│ │ ├── Controllers/ # AgentsController, CommandController, LogsController
|
||
│ │ ├── Hubs/ # AgentStatusHub, IAgentStatusClient, AgentStatusModels
|
||
│ │ ├── Models/ # AgentMinionMapping
|
||
│ │ ├── Services/ # AgentMinionMapperService, GatewayEventBridgeService
|
||
│ │ ├── Program.cs
|
||
│ │ └── appsettings.json
|
||
│ ├── Configurations/ # AgentConfiguration
|
||
│ ├── Data/ # AppDbContext, AppDbContextFactory
|
||
│ ├── Dtos/ # AgentStatusUpdateDto
|
||
│ ├── Entities/ # Agent, AgentStatus
|
||
│ ├── Migrations/ # EF migrations
|
||
│ ├── Models/ # AgentState
|
||
│ └── Repositories/ # AgentStateRepository, IAgentStateRepository
|
||
├── frontend/
|
||
│ └── src/app/
|
||
│ ├── layout/ # LayoutShell, HeaderBar, NavRail, BottomNav
|
||
│ ├── pages/ # hub, logs, projects, sessions, settings
|
||
│ ├── components/ # AgentCard, AgentStatusBadge, TaskProgressBar,
|
||
│ │ # QuickJumpButton, QuickJumpDrawer,
|
||
│ │ # GlobalActionModal, AdaptiveNavigation
|
||
│ ├── command-hub/ # AgentCard command hub view
|
||
│ ├── models/ # Agent model, AgentStatus, AgentCardData, Nav
|
||
│ └── services/ # AgentStatusService (Angular Signals)
|
||
├── api-client/ # Shared TS client (models, SignalR WS, HTTP utils)
|
||
├── design/
|
||
│ ├── command-hub-spec.md
|
||
│ └── mockups/ # Desktop kiosk, mobile, quick-jump drawer
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Domain Model
|
||
|
||
### Agent
|
||
|
||
| Field | Type | Description |
|
||
|---|---|---|
|
||
| `Id` | `Guid` | Primary key |
|
||
| `Status` | `AgentStatus` | Current agent state |
|
||
| `Task` | `string?` | Active task description |
|
||
| `Progress` | `int?` | Task completion % (0–100) |
|
||
| `SessionKey` | `string` | OpenClaw session identifier |
|
||
| `Channel` | `string` | Source channel (telegram, slack, etc.) |
|
||
| `LastActivity` | `DateTime` | Last event timestamp |
|
||
| `CreatedAt` / `UpdatedAt` | `DateTime` | Audit fields |
|
||
|
||
### AgentStatus enum
|
||
|
||
| Value | Integer | Meaning |
|
||
|---|---|---|
|
||
| `Active` | 0 | Agent is executing a task |
|
||
| `Idle` | 1 | Agent is waiting for work |
|
||
| `Thinking` | 2 | Agent is reasoning/planning |
|
||
| `Error` | 3 | Agent hit an unrecoverable state |
|
||
|
||
---
|
||
|
||
## Key Design Decisions
|
||
|
||
1. **Angular Signals** — Reactive state management. No NgRx — kept intentionally simple.
|
||
2. **Adaptive layout** — Sidebar nav (NavRail) on desktop/kiosk (≥768px); bottom nav on mobile.
|
||
3. **Tactical Dark Mode** — Theme via CSS custom properties in `styles.scss`.
|
||
4. **SignalR fleet group** — Clients call `JoinFleet()` to subscribe to all agent updates broadcast by the hub.
|
||
5. **Backend push model** — Hub uses `IHubContext<AgentStatusHub, IAgentStatusClient>` extension methods to push to clients; no polling.
|
||
6. **Gateway bridge** — `GatewayEventBridgeService` connects the OpenClaw gateway WebSocket to the SignalR hub.
|
||
|
||
---
|
||
|
||
## Getting Started
|
||
|
||
### Prerequisites
|
||
|
||
- .NET 8 SDK
|
||
- Node.js 20+
|
||
- Docker
|
||
- PostgreSQL
|
||
- Running OpenClaw gateway (for live agent events)
|
||
|
||
### Backend
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# Restore and build
|
||
dotnet restore
|
||
dotnet build
|
||
|
||
# Apply migrations
|
||
dotnet ef database update --project ControlCenter
|
||
|
||
# Run API
|
||
dotnet run --project ControlCenter
|
||
```
|
||
|
||
API runs at `http://localhost:5000` · Swagger at `http://localhost:5000/swagger`
|
||
|
||
### Frontend
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
ng serve
|
||
```
|
||
|
||
Frontend runs at `http://localhost:4200`
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
`backend/ControlCenter/appsettings.json` — override in `appsettings.Development.json` or environment variables:
|
||
|
||
| Key | Default | Description |
|
||
|---|---|---|
|
||
| `ConnectionStrings:DefaultConnection` | *(set in dev config)* | PostgreSQL connection string |
|
||
| `Gateway:WebSocketUrl` | `ws://localhost:3271/ws` | OpenClaw gateway WebSocket URL |
|
||
| `Gateway:AuthToken` | `""` | Gateway auth token |
|
||
| `Cors:AllowedOrigins` | `localhost:4200`, `localhost:5000` | Frontend origins for CORS |
|
||
|
||
---
|
||
|
||
## Real-Time Events
|
||
|
||
SignalR hub endpoint: `/hubs/agent-status`
|
||
|
||
### Hub Methods (server → client)
|
||
|
||
| Method | Payload | Description |
|
||
|---|---|---|
|
||
| `ReceiveStatusUpdate` | `AgentStatusUpdateDto` | Agent status changed |
|
||
| `ReceiveAgentList` | `Agent[]` | Full fleet snapshot on join |
|
||
|
||
### Client → Server
|
||
|
||
| Method | Description |
|
||
|---|---|
|
||
| `JoinFleet()` | Subscribe to all agent updates |
|
||
| `LeaveFleet()` | Unsubscribe |
|
||
| `SendStatusUpdate(dto)` | Push a status update (internal use) |
|
||
|
||
---
|
||
|
||
## Pages
|
||
|
||
| Route | Page | Description |
|
||
|---|---|---|
|
||
| `/hub` | Command Hub | Live agent grid — status, task, progress |
|
||
| `/logs` | Logs | Agent session log viewer |
|
||
| `/projects` | Projects | Linear project tracking view |
|
||
| `/sessions` | Sessions | OpenClaw session browser |
|
||
| `/settings` | Settings | App configuration |
|
||
|
||
---
|
||
|
||
## Agent Fleet
|
||
|
||
| Agent | Role |
|
||
|---|---|
|
||
| Otto | Orchestrator — owns the dev lifecycle |
|
||
| Rex | Frontend (Angular) |
|
||
| Dex | Backend (ASP.NET Core) |
|
||
| Hex | Database (schema, migrations) |
|
||
| Pip | Raspberry Pi / Python |
|
||
| Nano | Arduino / ESP32 / ESPHome |
|
||
| Sketch | UX/UI design |
|
||
| Flip | Mobile development |
|
||
| Bob | Content & marketing copy |
|
||
| Stuart | Concept visualization (images) |
|
||
| Norbert | 3D design (OpenSCAD) |
|
||
|
||
---
|
||
|
||
## Branch & PR Rules
|
||
|
||
- All feature branches target `dev` — **never `main`**
|
||
- Branch naming: `agent/<agent>/CUB-N-short-description`
|
||
- PR titles: `CUB-N: short description`
|
||
- PRs require Otto review before Joshua merges
|
||
|
||
---
|
||
|
||
## API Overview
|
||
|
||
| Route prefix | Resource |
|
||
|---|---|
|
||
| `/api/agents` | Agent registry and status |
|
||
| `/api/command` | Issue commands to agents |
|
||
| `/api/logs` | Session log retrieval |
|
||
|
||
Full schema at `/swagger` when running in dev.
|
||
|
||
---
|
||
|
||
*Built by CubeCraft Creations · Orchestrated by Otto*
|