repos/Laddr/dashboard/README.md

Laddr Dashboard

The official Laddr dashboard, distributed as a Docker image for seamless integration with Laddr projects.

🎯 Overview

This directory contains the React-based dashboard that provides comprehensive observability for Laddr agent systems. The dashboard is built and distributed as a Docker image (laddr/dashboard:latest) so users never need to touch frontend code.

🏗️ Architecture

dashboard/
├── src/                  # React application source
│   ├── App.tsx          # Main application component
│   ├── main.tsx         # Application entry point
│   └── ...
├── public/              # Static assets
├── Dockerfile           # Development Dockerfile
├── Dockerfile.prod      # Production Dockerfile (multi-stage)
├── nginx.conf           # Nginx configuration for production
├── vite.config.ts       # Vite build configuration
├── package.json         # Dependencies and scripts
└── build-dashboard.sh   # Build script for Docker image

📦 Distribution Model

For Users

• Dashboard is NOT copied to user projects
• Distributed as pre-built Docker image
• Automatically pulled when running laddr run dev
• Zero frontend setup required

For Maintainers

• Build and publish Docker images to Docker Hub
• Multi-stage build: Node.js → Nginx
• Optimized for production (~40MB final size)

🚀 Building the Dashboard

Development

# Install dependencies
npm install

# Run development server
npm run dev
# Dashboard available at http://localhost:5173

# Build for production
npm run build
# Output in dist/

Production Docker Image

# Build Docker image
./build-dashboard.sh v1.0.0

# Or manually
docker build -f Dockerfile.prod -t laddr/dashboard:latest .

# Test locally
docker run -p 5173:5173 laddr/dashboard:latest

# Push to Docker Hub
docker push laddr/dashboard:latest
docker push laddr/dashboard:v1.0.0

🔧 Technical Details

Multi-Stage Build

Stage 1: Builder

• Base: node:20-alpine
• Installs dependencies with npm ci
• Builds React app with Vite
• Output: Optimized static files

Stage 2: Server

• Base: nginx:alpine
• Copies built files from builder
• Includes custom nginx configuration
• Final size: ~40MB

Nginx Configuration

The production image uses nginx to:

• Serve static files with caching and compression
• Proxy /api/* requests to API container
• Proxy /ws/* WebSocket connections
• Handle React Router client-side routing
• Optimize with gzip compression

location /api/ {
    proxy_pass http://api:8000/api/;
    # ... proxy headers
}

location /ws/ {
    proxy_pass http://api:8000/ws/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Environment Variables

The dashboard uses environment variables for configuration:

• VITE_API_URL: API server URL (default: http://api:8000)
• VITE_WS_URL: WebSocket URL (default: ws://api:8000)

📊 Features

The dashboard provides:

1. System Overview

   • Active agents count
   • Job queue status
   • System health metrics

2. Agent Management

   • View all registered agents
   • Check agent status and queue depth
   • Agent details (role, goal, tools)
   • Chat with individual agents

3. Observability

   • View distributed traces
   • Monitor metrics and performance
   • Real-time logs via WebSocket
   • Token usage tracking

4. Job Management

   • Submit new jobs
   • Monitor job status
   • View results
   • Cancel running jobs

5. Real-time Updates

   • WebSocket for live logs
   • System event streaming
   • Agent status updates

🔗 API Integration

The dashboard communicates with the Laddr API server:

REST Endpoints

• GET /api/agents - List agents
• GET /api/agents/{name} - Get agent details
• POST /api/agents/{name}/chat - Chat with agent
• GET /api/jobs - List jobs
• POST /api/jobs - Submit job
• GET /api/traces - Get traces
• GET /api/metrics - Get metrics

WebSocket Endpoints

• WS /ws/logs/{agent} - Stream agent logs
• WS /ws/events - Stream system events

🧪 Testing

# Run tests
npm test

# Run linting
npm run lint

# Type checking
npm run type-check

# Preview production build
npm run build
npm run preview

📦 Dependencies

Core

• React 18.3 - UI framework
• React Router 6 - Client-side routing
• TypeScript - Type safety

Data Fetching

• TanStack Query 5 - Server state management
• Axios - HTTP client

UI Components

• Recharts - Data visualization
• Lucide React - Icons

Build Tools

• Vite 5 - Build tool and dev server
• TypeScript - Type checking

🔄 Release Process

1. Update version in package.json
2. Build image: ./build-dashboard.sh v1.x.x
3. Test locally: docker run -p 5173:5173 laddr/dashboard:v1.x.x
4. Push to Docker Hub: docker push laddr/dashboard:v1.x.x
5. Tag as latest: docker push laddr/dashboard:latest
6. Update docs: Note version in changelog

🐛 Troubleshooting

Build fails

# Clean and rebuild
rm -rf node_modules dist
npm install
npm run build

Docker image too large

• Check multi-stage build is working
• Verify node_modules not copied to final image
• Use docker images to check size

API connection fails

• Verify nginx proxy configuration
• Check CORS settings in API server
• Ensure API container is running
• Check network connectivity between containers

📚 Resources

• Vite Documentation
• React Documentation
• Nginx Documentation
• Docker Multi-stage Builds

🤝 Contributing

For maintainers working on the dashboard:

1. Make changes in src/
2. Test locally with npm run dev
3. Build production image
4. Test Docker image locally
5. Push to Docker Hub
6. Update documentation

📄 License

Same as Laddr project license.

---

Note: This dashboard is designed to be distributed as a Docker image. Users should never need to modify or build it themselves. All customization is done via environment variables and API configuration.