Skip to main content

SWARM Dashboard Integration Guide

Quick Start: Adding SwarmDashboard to ValkyrAI​

Step 1: Import SwarmDashboard​

In your main dashboard component (e.g., Dashboard.tsx or index.tsx):

import SwarmDashboard from "./dashboard/SwarmDashboard";

Step 2: Add Route​

If using React Router:

import { BrowserRouter, Routes, Route } from "react-router-dom";

<Routes>
  <Route path="/dashboard" element={<Dashboard />} />
  <Route path="/dashboard/swarm" element={<SwarmDashboard />} />
  {/* ... other routes */}
</Routes>;

Or as a Tab in existing Dashboard:

const Dashboard = () => {
  const [activeTab, setActiveTab] = useState("overview");

  return (
    <div className="dashboard">
      <TabBar>
        <Tab onClick={() => setActiveTab("overview")}>Overview</Tab>
        <Tab onClick={() => setActiveTab("swarm")}>SWARM</Tab>
      </TabBar>

      {activeTab === "overview" && <OverviewPanel />}
      {activeTab === "swarm" && <SwarmDashboard />}
    </div>
  );
};

Step 3: Verify WebSocketContext​

SwarmDashboard requires WebSocketContext. Ensure it's available:

import { WebSocketProvider } from "../websocket/WebSocketContext";

<WebSocketProvider>
  <SwarmDashboard />
</WebSocketProvider>;

Step 4: Add CSS​

Make sure SwarmDashboard.css is imported (already done in component):

.swarm-dashboard {
  width: 100%;
  height: 100%;
  display: flex;
}

.swarm-visualizer-container {
  width: 100%;
  height: 100%;
  background: #0a0e27;
  position: relative;
}

.swarm-split {
  width: 100%;
  height: 100%;
}

.swarm-divider {
  background: linear-gradient(to bottom, #00ff00, transparent, #00ff00);
  width: 2px;
  opacity: 0.5;
}

Component API Reference​

SwarmDashboard​

Props: None (autonomous component)

Exposes:

  • Split pane layout with 65% visualizer, 35% control panel
  • Real-time agent monitoring

Example Usage:

<SwarmDashboard />

SwarmVisualizer3D​

Props:

interface SwarmVisualizerProps {
  onAgentSelected?: (agent: Agent) => void;
  onCommandExecute?: (agentId: string, command: any) => void;
}

Imperative Handle:

interface SwarmVisualizerHandle {
  _triggerGlow: (agentId: string) => void;
}

Example Usage:

const visualizerRef = useRef<SwarmVisualizerHandle>(null);

// Trigger glow on command execution
visualizerRef.current?._triggerGlow("agent-123");

// Render
<SwarmVisualizer3D
  ref={visualizerRef}
  onAgentSelected={handleSelection}
  onCommandExecute={handleCommand}
/>;

SwarmControlPanel​

Props:

interface SwarmControlPanelProps {
  selectedAgent?: Agent | null;
  onCommandExecute?: (agentId: string, command: any) => void;
  visualizerRef?: React.RefObject<SwarmVisualizerHandle>;
}

Example Usage:

<SwarmControlPanel
  selectedAgent={selectedAgent}
  onCommandExecute={handleCommand}
  visualizerRef={visualizerRef}
/>

Data Flow​

Agent Registration Flow​

ValorIDE Client
    ↓
MothershipService.register()
    ↓
WebSocket: /app/swarm/register
    ↓
ValkyrAI: SwarmRegistryService.register(agentId, metadata)
    ↓
Broadcast: /topic/agents
    ↓
SwarmVisualizer3D listens 'websocket-message' event
    ↓
Agent nodes rendered in orbit

Command Execution Flow​

SwarmControlPanel
    ↓
handleCommand(agentId, commandText)
    ↓
socket.send("/app/swarm/command", {agentId, command})
    ↓
ValkyrAI: SwarmRegistryService.forwardCommand()
    ↓
Publish: /topic/agent-commands (broadcast)
    ↓
SwarmDashboard.handleCommandExecute()
    ↓
visualizerRef.current._triggerGlow(agentId)
    ↓
Agent node glows for 1.5 seconds
    ↓
Command history updates

WebSocket Message Format​

Agent Registration​

{
  "id": "uuid",
  "type": "SERVICE",
  "time": 1234567890,
  "payload": {
    "action": "register",
    "instanceId": "valoride-instance-1",
    "userId": "user@example.com",
    "timestamp": 1234567890
  }
}

Agent List Update (from /topic/agents)​

{
  "agents": [
    {
      "id": "valoride-instance-1",
      "userId": "user@example.com",
      "version": "1.0.0",
      "lastSeen": "2025-12-20T10:30:00Z",
      "status": "active"
    }
  ]
}

Command Execution​

{
  "id": "uuid",
  "type": "PRIVATE",
  "time": 1234567890,
  "payload": {
    "sourceInstanceId": "dashboard",
    "targetInstanceId": "valoride-instance-1",
    "command": "ping",
    "data": {}
  }
}

Testing Checklist​

  • SwarmDashboard renders without errors
  • WebSocketContext is available in component tree
  • Agent list updates when new agent registers
  • Agent nodes appear in 3D orbit visualization
  • Selected agent highlights in roster
  • Command input accepts text
  • Preset command buttons work (ping, status, etc.)
  • Commands are sent via WebSocket
  • Agent node glows when command executed
  • Command history updates with new entries
  • Glow animation lasts ~1.5 seconds
  • Split pane resizes smoothly
  • No console errors in browser
  • 3D scene renders at 60 FPS (dev tools)
  • Mobile viewport doesn't break layout

Troubleshooting​

Issue: Agent list not updating​

Solution: Check WebSocket connection status in browser console

// In browser console
window.dispatchEvent(
  new CustomEvent("websocket-message", {
    detail: { payload: { agents: [] } },
  })
);

Issue: Glow animation not triggering​

Solution: Verify visualizerRef is properly forwarded

console.log(visualizerRef.current?._triggerGlow); // Should be a function

Issue: Three.js canvas not rendering​

Solution: Check browser console for WebGL errors, ensure:

  • WebGL 2.0 support enabled
  • Proper canvas container size
  • No CSS conflicts with canvas styling

Issue: Performance issues with many agents​

Solution: Implement agent culling (see Performance section in SWARM_COMPONENTS_STATUS.md)

Styling Customization​

Override LCARS Theme​

/* SwarmControlPanel.css overrides */
.swarm-header {
  background: your-color !important;
  border: 1px solid your-border-color !important;
}

.agent-item.active {
  background: your-active-color !important;
}

Three.js Scene Colors​

In SwarmVisualizer3D.tsx:

// Central core color (mothership)
scene.background = new THREE.Color(0x0a0e27); // Dark blue
pointLight.color = new THREE.Color(0x00ff00); // Neon green
pointLight2.color = new THREE.Color(0x0099ff); // Cyan

Performance Tips​

  1. Agent Culling: Only render agents within camera frustum
  2. LOD (Level of Detail): Use simpler geometry for distant agents
  3. Instancing: Use THREE.InstancedMesh for many identical nodes
  4. Texture Optimization: Use compressed textures (WEBP)
  5. WebSocket Throttling: Limit agent updates to 10/sec max

Next Steps​

  1. ✅ Components compiled successfully
  2. 🟡 Integrate into dashboard routing
  3. 🟡 Verify WebSocket integration in dashboard context
  4. 🟡 Run smoke tests
  5. 📋 Add unit/integration tests
  6. 📋 Performance profiling with 50+ agents
  7. 📋 User acceptance testing
  8. 📋 Deploy to production

For more details, see:

  • SWARM_COMPONENTS_STATUS.md - Detailed status and architecture
  • README_SWARM.md (ValkyrAI) - Backend integration
  • README_SWARM.md (ValorIDE) - Client integration