# ClawCenter Dashboard: Interface & Real-time Signals

> **Navigation**: [← Index Hub](../../INDEX.md)

This document describes the design system, real-time communication protocols, and visual standards for the ClawCenter dashboard.

## 🚢 Dashboard Architecture

The dashboard is built with **Next.js (App Router)** and **Tailwind CSS**. It serves as the primary visual interface for monitoring agent swarms and performing system audits.

### Mission Control Mode

A specialized, high-density dashboard state for human-agent collaboration, featuring real-time task visualization, trust monitoring, and human-in-the-loop (HITL) intervention gates.

#### Tactical Stability & Persistence

To ensure a consistent "in-command" experience, the Mission Control interface implements:

- **Geometry Locking**: Buttons and controls use fixed minimum widths (`min-w-[110px]`) and transparent borders to prevent "jiggling" or 1px shifts when toggling the Mission Control or Intelligence modes.
- **Contextual Persistence**: Tactical sidebars (**Mission Briefing** and **Mission Control HUD**) persist during new chat initialization. Even before a session ID is assigned, the commander maintains a view of the operational theater.
- **Typography Polish**: Tactical metrics are rendered as distinct blocks with descriptive labels, preventing text merging during high-velocity updates.

---

## 🔒 Multi-tenant Data Isolation (Perspective G)

The dashboard enforces strict logical separation between tenants to prevent data leakage and unauthorized cross-workspace operations.

### API Hardening & Scoping (Hardened Pattern)

All dashboard API routes (`/api/...`) implement mandatory isolation layers following a standardized **Extract → Verify → Scope** pattern:

1.  **Identity Extraction**: Extracts the `userId` from the session cookie using `getUserId()` and explicitly blacklists the `SYSTEM` identity.
2.  **Workspace Identification**: Resolves `workspaceId` using a prioritized lookup cascade:
    - `searchParams.get('workspaceId')` (Direct URL override)
    - `request.headers.get('x-workspace-id')` (CLI / Header-based override)
    - `cookies().get('workspaceId')` (Frontend persistent context)
    - Fallback to `'default'` if unprovided.
3.  **Permission Gating**: Every request is verified against the `IdentityManager` to ensure the user has the required permission for the specific `workspaceId` (e.g., `AGENT_VIEW`, `EVOLUTION_APPROVE`, `WORKSPACE_MEMBERS`).
4.  **Mandatory Scoping**: Data retrieval and mutation are strictly partitioned via `workspaceId`.
    - **Memory/Config**: Lookups use the `WS#${workspaceId}#` prefix.
    - **Scans/Queries**: DynamoDB `ScanCommand` and `QueryCommand` calls include a `FilterExpression` on the `workspaceId` field, or ideally use GSIs scoped by `workspaceId`.
    - **Global Actions**: Global actions (e.g., "Purge All Traces") are strictly scoped to the user's active workspace. Global listing (e.g., `GET /api/workspaces`) is filtered by explicit user membership.

### Drift Detection & Consistency

The dashboard periodically probes for consistency across silos:

- **Resilience Metrics**: Aggregates recovery operations scoped by `workspaceId`.
- **Cognitive Health**: Visualizes agent stability metrics partitioned by tenant.

---

## 🕹️ Mission Control Components

The dashboard introduces a set of specialized interactive components for co-managing the swarm:

### 1. Interactive Swarm Canvas (React Flow)

Visualizes the execution DAG of the swarm in real-time.

- **Node Deep-Dive**: Clicking a node opens the **TraceDetailSidebar**, providing real-time streaming logs (via AG-UI) and tool usage audit.
- **Attachment Presence**: Visualizes staged media (📎) directly on the task nodes to show data flow.

### 2. Council Judge Panel

A decision-gate component that activates when the **Council of Agents** requires human governance.

- **Synthesis Engine**: Merges conflicting reviews from Security, Architect, and Performance specialists.
- **Action Suite**: Provides "Overrule", "Approve with Directives", or "Veto" capabilities.

### 3. The Scales (Trust & Cognitive Health)

A real-time metrics cluster showing the stability and reputation of the active swarm.

- **Anomaly Highlight**: Triggers visual warnings when reasoning loops or cognitive degradation are detected.
- **Autonomy Mode**: Allows global toggling between `AUTO` and `HITL` modes.

### 4. Trace Intelligence View

The primary interface for auditing historical and live traces. It has been modularized into a hierarchy of single-responsibility components for maximum maintainability:

#### Component Hierarchy (ASCII)

```text
TraceIntelligenceView (Parent)
├── StatsBar
│   └── [Total Ops, Active Sessions, Tools Invoked, Token Cost]
├── FilterBar
│   ├── Tab Switcher (Live, Timeline, Sessions, Agents, Models, Tools)
│   └── Filters (Search, Status, Source, Date)
├── TraceCard (Individual Trace Visualization)
└── GroupedTableView (Tabular view for Agents/Models/Tools)
```

- **Modular State Management**: Shared types and filtering logic are encapsulated in `components/TraceIntelligence/types.ts`.
- **Enriched Telemetry**: Each trace is augmented with `toolsUsed`, `totalTokens`, and model attribution during the render phase for high-fidelity auditing.

### 5. Neural Tuning Ground

A Human-in-the-Loop (HITL) curation queue designed to support the system's fine-tuning pipelines.

- **Trace Curation**: Allows administrators to review, approve, or reject high-quality execution traces stored in the Data Lake.
- **Dataset Export**: Enables exporting approved traces in JSONL format for offline analysis or manual training.
- **Fine-Tuning Trigger**: Provides a centralized action to trigger specialized model fine-tuning jobs (supporting DeepSeek v4 Flash, MiniMax 2.7, etc.) once a critical mass of verified traces is curated.

---

### Real-time Communication (MQTT)

ClawCenter uses **AWS IoT Core** to provide low-latency, bi-directional communication between the serverless backend and the browser.

| Channel Type       | Endpoint (MQTT Topic)   | Purpose                                                     |
| :----------------- | :---------------------- | :---------------------------------------------------------- |
| **Agent Chunks**   | `users/{userId}/chunks` | Streaming text fragments from agents                        |
| **System Signals** | `users/{userId}/signal` | Deployment status and health alerts and per-session signals |
| **Trace Updates**  | `users/{userId}/traces` | Real-time DAG execution updates                             |

#### Topic Taxonomy (application namespaces)

The realtime Bridge and publisher code use these application-level topic namespaces which the IoT custom authorizer grants access to:

- `users/{userId}/...` (primary per-user channel, includes `signal`, `chunks`, `sessions/{sessionId}/signal`, `traces`, etc.)
- `workspaces/{workspaceId}/signal`
- `collaborations/{collaborationId}/signal`
- `system/metrics` (global system telemetry)

These topics are used by the `RealtimeBridge` implementation which routes EventBridge events into the appropriate MQTT topic (see core/handlers/bridge.ts).

#### Signal Flow

1. **Backend**: A Lambda agent emits a signal to the `AgentBus`.
2. **Bridge**: The `Real-time Bridge` handler captures the event.
3. **IoT**: The Bridge publishes the event to the user's MQTT topic.
4. **Browser**: The dashboard (via `useRealtime` hook) receives and renders the signal.

---

#### Realtime Auth Contract

The dashboard connects to AWS IoT using a WebSocket `wss://.../mqtt` URL returned by the config API. Connection details are exposed by the server via the dashboard config endpoint (`/api/config`) and consumed by the client `useRealtime` hook.

- Connection URL: the client connects to the WebSocket path at the `realtime.url` value and appends query parameters:
  - `x-amz-customauthorizer-name=<AuthorizerName>` — _optional_; included when the IoT custom authorizer name is provided by the config API.
  - `token=<clientToken>` — **required** by the custom authorizer. The dashboard will generate and persist a short, non-sensitive client token in browser `localStorage` under the key `sc_realtime_token` so reconnects reuse the same token.

- Token constraints: the custom authorizer requires a token string (server-side logic expects at least 10 characters). The token is not a credential with IAM rights; it is a lightweight client identifier used by the custom authorizer for session scoping.

- Implementation notes: The `useRealtime` hook constructs the full `mqtt.connect(...)` WebSocket URL (adds the authorizer name when present and the `token` query param), uses `protocol: 'wss'` and a generated `clientId`, and manages default subscriptions to `users/{userId}/#`.

- Important: do **not** rely on HTTP Basic username/password placeholders for IoT WebSocket auth — the correct contract is the query-parameter `token` (and optional custom authorizer name) as implemented by `useRealtime` and validated by `core/handlers/realtime-auth.ts`.

---

## 🔌 Extension Architecture (Spoke Injection)

The dashboard implements a "Hub-and-Spoke" UI model, allowing domain-specific projects (like VoltX) to inject custom pages, sidebar items, and components without modifying the core framework.

### Extension Signal Flow (ASCII)

```text
[ Dashboard Hub ]           [ Extension Loader ]           [ Domain Spoke ]
       |                           |                             |
       |--- (Mount) -------------->|                             |
       |                           |--- (Dynamic Import) ------->| (extensions/index.ts)
       |                           |                             |
       |                           |<-- (init API) --------------|
       |                           |                             |
       | <--- (Register Items) ----|                             |
       |                           |                             |
[ Sidebar/Layouts Update ] <-------|                             |
```

### 1. Sidebar Extensions

Plugins can register custom navigation items. These items support RBAC (Role-Based Access Control) and are dynamically merged into the main sidebar.

### 2. Dynamic Components

Plugins can register custom React components that the framework can render dynamically (e.g., in the chat interface or specialized dashboards).

### 3. Layout Slots

Specialized "slots" (e.g., `sidebar_bottom`, `header_right`) allow plugins to inject UI elements into existing framework layouts.

---

## 🎨 Design System & Theme

The dashboard follows a "Cyber-Industrial" aesthetic, prioritized for high-density information display and tactical observability.

### Color Palette (The "Stellar" Palette)

The theme is entirely driven by CSS variables defined in [`dashboard/src/globals.css`](../../dashboard/src/globals.css).

| Category        | Variable        | Purpose                                      |
| :-------------- | :-------------- | :------------------------------------------- |
| **Background**  | `--background`  | Main surface color (Pitch black / Off-white) |
| **Foreground**  | `--foreground`  | Primary text and high-contrast lines         |
| **Cyber Green** | `--cyber-green` | Success, running, and healthy states         |
| **Cyber Amber** | `--cyber-amber` | Warnings and in-progress tasks               |
| **Cyber Red**   | `--cyber-red`   | Errors, failures, and circuit breaker active |

### UI Best Practices

1. **Avoid Hardcoded Hex Codes**: Always use Tailwind's semantic utility classes (e.g., `text-foreground` instead of `text-white`).
2. **Adaptive Transparency**: Use Tailwind's opacity modifier for borders (e.g., `border-foreground/10`) to ensure they scale with the theme.
3. **Micro-animations**: Use subtle transitions on hover and state changes to make the interface feel alive.
4. **Smart Tooltips**: Use the `CyberTooltip` component for all action buttons and information icons. It uses React Portals to avoid stacking context issues and features smart positioning to stay within the viewport.

---

## Observation & Metrics Integrity

The dashboard enables high-fidelity observation of system internals, ensuring the backend trace state matches external reporting.

### 1. Consistency Probing

To detect drift between raw metrics and visual reporting, the **ConsistencyProbe** cross-references independent data sources:

- **Source A**: CloudWatch Metrics / DynamoDB Rollups (`TokenRollup`).
- **Source B**: The `TraceTable` (queried via `AgentIdIndex` GSI).
- **Goal**: Ensure completion counts, success rates, and `p95DurationMs` latency metrics match across the stack.

### 2. Trace Performance Tracking

Execution latency and token consumption are tracked per-agent and per-trace:

- **Metrics**: Percentiles (p50, p95) are calculated via the `CognitiveMetrics` background handlers and visualized in the System Pulse.
- **Evolution ROI**: Real-time tool performance and ROI metrics are tracked via `EvolutionMetrics` with mandatory multi-tenant scoping, enabling per-workspace cost/benefit analysis.

### 3. Proactive Failure Emission

Dashboard errors are emitted immediately for live remediation:

- **Signal**: `DASHBOARD_FAILURE_DETECTED` event.
- **Optics**: The `CognitiveHealthAPI` reads from the `HEALTH#SNAPSHOT#` prefix to provide instant system health visualization.

---

## 🧪 Development & Testing

To work on the dashboard UI locally:

```bash
# Start local dev server
cd dashboard
npm run dev
```

The dashboard uses **Vitest** for component testing. Ensure all UI changes pass before deploying:

```bash
cd dashboard
npm test
```

> [!TIP]
> Use the `THEME_DEBUG` toggle in the settings panel to quickly switch between Dark and Light modes for contrast testing.
