# Amicus Web Dashboard
Real-time visualization and monitoring for the Amicus Synapse cluster.
## Features
### 🖥️ Node Monitoring
- Live node status (active/inactive)
- Node role and model information
- Heartbeat timestamps
- Visual health indicators
### 📊 Task Visualization
- Real-time task activity charts
- Pending vs completed task counts
- Recent task history with status
- Task assignment tracking
### ⚡ Performance Metrics
- Total events tracked
- Unique metrics collected
- Node participation stats
- Database size monitoring
- Time-range analytics
### 🔄 Real-Time Updates
- WebSocket integration for live updates
- Auto-refresh every 5 seconds
- Connection status indicator
- Automatic reconnection
## Quick Start
### Option 1: Using the startup script (Recommended)
```bash
./scripts/start-dashboard.sh
```
This will:
1. Check for WebSocket server (port 8765)
2. Start it if not running
3. Launch the dashboard on http://localhost:5000
### Option 2: Manual startup
**Terminal 1 - WebSocket Server:**
```bash
python -m src.amicus.websocket_server
```
**Terminal 2 - Dashboard:**
```bash
python src/amicus/dashboard.py
```
Then open http://localhost:5000 in your browser.
## Architecture
```
┌─────────────┐
│ Browser │
│ Dashboard │
└──────┬──────┘
│
├─── HTTP REST API ─────> Flask Server ───> state.json
│ └───> metrics.db
│
└─── WebSocket ────────> WebSocket Server
(port 8765)
```
## REST API Endpoints
### `GET /`
Returns the dashboard HTML interface
### `GET /api/state`
Returns current cluster state:
```json
{
"cluster_nodes": {
"copilot-node-1": {
"role": "bootstrap_manager",
"model": "claude-sonnet-4.5",
"status": "working",
"last_heartbeat": 1770104500.0
}
},
"next_steps": [...],
"summary": "..."
}
```
### `GET /api/metrics`
Returns metrics database statistics:
```json
{
"total_events": 1523,
"unique_metrics": 12,
"unique_nodes": 4,
"db_size_bytes": 245760,
"time_range_hours": 27.8
}
```
### `GET /api/metrics/recent`
Returns recent metric events (last hour, limit 100)
## WebSocket Integration
The dashboard connects to the WebSocket server and subscribes to:
- `state.update` - Cluster state changes
- `task.completed` - Task completions
- `task.claimed` - Task assignments
## UI Components
### Header
- Active node count
- Pending tasks
- Completed tasks
- Dashboard uptime
### Cluster Nodes Panel
- Node cards with:
- Node ID and status badge
- Role and model
- Time since last heartbeat
- Visual inactive state
### Task Activity Chart
- Line chart with Chart.js
- Two datasets: Completed (green) vs Pending (orange)
- Time-series visualization
- Auto-scrolling (keeps last 20 data points)
### Performance Metrics Panel
- Total events
- Unique metrics
- Tracked nodes
- Database size
- Time range
### Recent Tasks Panel
- Last 5 tasks
- Status indicators (completed/pending)
- Assigned node
- Visual status colors
## Styling
- Dark theme optimized for long viewing sessions
- Purple gradient header (#667eea → #764ba2)
- Responsive grid layout (auto-fit minmax 400px)
- Smooth hover transitions
- Color-coded status indicators:
- 🟢 Green: Active/Completed
- 🟡 Orange: Pending
- ⚪ Gray: Inactive
## Browser Requirements
- Modern browser with WebSocket support
- JavaScript enabled
- Recommended: Chrome, Firefox, Safari, Edge (latest versions)
## Troubleshooting
### Dashboard shows "Disconnected"
- Check that WebSocket server is running: `nc -z localhost 8765`
- Start server: `python -m src.amicus.websocket_server`
### No nodes appear
- Verify cluster state exists: `cat ~/.amicus/state.json`
- Register a node using Amicus tools
### Metrics show 0
- Check metrics database: `ls -lh ~/.amicus/metrics.db`
- Ensure metrics collection is enabled
- Run some tasks to generate metrics
### Port 5000 already in use
Edit `src/amicus/dashboard.py` and change:
```python
app.run(host='0.0.0.0', port=5000, debug=True)
```
to another port like 5001.
## Development
### Running in debug mode
```bash
export FLASK_ENV=development
python src/amicus/dashboard.py
```
### Auto-reload on changes
Flask's debug mode (default) will auto-reload on code changes.
### Testing API endpoints
```bash
# Get state
curl http://localhost:5000/api/state | jq
# Get metrics
curl http://localhost:5000/api/metrics | jq
```
## Future Enhancements
Planned features:
- [ ] Historical time-range selection
- [ ] Export metrics to CSV/JSON
- [ ] Interactive node controls (pause/resume)
- [ ] Log streaming viewer
- [ ] Cost tracking dashboard
- [ ] Alert configuration
- [ ] Mobile-responsive improvements
- [ ] Dark/light theme toggle
## Security Notes
**Development Use Only**
This dashboard runs with:
- CORS enabled for all origins
- No authentication
- Debug mode enabled
For production deployment:
1. Disable debug mode
2. Add authentication (JWT, OAuth, etc.)
3. Configure CORS properly
4. Use HTTPS/WSS
5. Run behind reverse proxy (nginx)
## Performance
- **Initial load**: ~100ms (HTML + Chart.js CDN)
- **API response**: <50ms (local SQLite)
- **WebSocket latency**: <10ms (local connection)
- **Memory usage**: ~50MB (Flask + Chart.js)
- **Refresh rate**: 5 seconds (configurable)
## Dependencies
- Flask >= 3.0
- flask-cors >= 6.0
- Chart.js 4.4.0 (CDN)
- WebSocket (built-in browser)
## Related Documentation
- [WebSocket Usage](WEBSOCKET_USAGE.md) - WebSocket server details
- [Metrics System](../research/METRICS_ANALYTICS_RESEARCH.md) - Metrics architecture
- [Cluster Management](BOOTSTRAP_MANAGER.md) - Node coordination
