Frontend Development Guidance

This guide covers the development, integration, and usage of UI components within the AlphaSwarm ecosystem.

Component Quick Reference

Component	Location	Purpose
PromotionGateModal	components/control-plane/	HITL approval for money-plane
AgentStatusGrid	components/control-plane/	Live agent monitoring
DrawdownChart	components/charts/	Drawdown visualization
ExposureHeatmap	components/risk/	Symbol × factor matrix
RiskDashboard	components/risk/	Comprehensive risk view

Getting Started

Installation

cd alphaswarm_ui
pnpm install

Development Server

pnpm dev

Environment Setup

Required environment variables in alphaswarm_ui/.env.local:

• ALPHASWARM_API_BASE: http://localhost:8000
• NEXT_PUBLIC_ALPHASWARM_LANGGRAPH_URL: http://localhost:2024 (consumed by AgentStatusGrid)

UI Integration Guide

1. Connecting to the Backend

Use the provided useApiQuery hook (a TanStack Query wrapper over the BFF fetch client) to interact with the API:

import { useApiQuery } from '@/hooks/useApiQuery';

const { data, isLoading } = useApiQuery({
  queryKey: ['agents', 'list'],
  path: '/agents/list',
});

2. Live Agent Monitoring

Integrate the AgentStatusGrid to show real-time agent health:

import { AgentStatusGrid } from '@/components/control-plane/AgentStatusGrid';

<AgentStatusGrid onViewThread={handleViewThread} />

Troubleshooting Frontend Issues

• HMR Not Working: Ensure you are using pnpm dev and not a production build.
• Hydration Errors: Check for mismatches between server-side and client-side rendering, especially when using browser-only globals like window or localStorage.
• API CORS Errors: Verify that the backend has the correct ALPHASWARM_WEBUI_CORS_ORIGINS configured to allow your local frontend URL.

Further Documentation

• For project-wide index, see the AlphaSwarm Index (alphaswarm_index repo).