# 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*