docs: update readme

README.md

@@ -1,10 +1,10 @@
 # SPORE UI
 
-A modern web interface for monitoring and managing SPORE embedded systems.
+Zero-configuration web interface for monitoring and managing SPORE embedded systems.
 
 ## Features
 
-- **🌐 Cluster Monitoring**: Real-time view of all cluster members
+- **🌐 Cluster Monitoring**: Real-time view of all cluster members with auto-discovery
 - **📊 Node Details**: Expandable cards with detailed system information
 - **🚀 Modern UI**: Beautiful glassmorphism design with smooth animations
 - **📱 Responsive**: Works on all devices and screen sizes
@@ -28,7 +28,6 @@ spore-ui/
 │   ├── index.html         # Main HTML page
 │   ├── styles.css         # All CSS styles
 │   ├── script.js          # All JavaScript functionality
-│   └── README.md          # Frontend documentation
 └── README.md              # This file
 ```
 
@@ -53,33 +52,63 @@ spore-ui/
 - **API**: SPORE Embedded System API
 - **Design**: Glassmorphism, CSS Grid, Flexbox
 
-## TODO
-
 ## UDP Auto Discovery
 
-The backend now includes automatic UDP discovery for SPORE nodes on the network. This eliminates the need for hardcoded IP addresses.
+The backend now includes automatic UDP discovery for SPORE nodes on the network. This eliminates the need for hardcoded IP addresses and provides a self-healing, scalable solution for managing SPORE clusters.
 
-### How It Works
+### 🚀 How It Works
 
 1. **UDP Server**: The backend listens on port 4210 for UDP messages
 2. **Discovery Message**: Nodes send `CLUSTER_DISCOVERY` messages to broadcast address `255.255.255.255:4210`
 3. **Auto Configuration**: When a discovery message is received, the source IP is automatically used to configure the SporeApiClient
 4. **Dynamic Updates**: The system automatically switches to the most recently seen node as the primary connection
+5. **Health Monitoring**: Continuous monitoring of node availability with automatic failover
 
-### Discovery Endpoints
+### 📡 Discovery Protocol
 
+- **Port**: 4210 (configurable via `UDP_PORT` constant)
+- **Message**: `CLUSTER_DISCOVERY` (configurable via `DISCOVERY_MESSAGE` constant)
+- **Broadcast**: `255.255.255.255:4210`
+- **Protocol**: UDP broadcast listening
+- **Auto-binding**: Automatically binds to the specified port on startup
+
+### 🔧 Setup Instructions
+
+#### Backend Setup
+```bash
+# Start the backend server
+npm start
+
+# The server will automatically:
+# - Start HTTP server on port 3001
+# - Start UDP discovery server on port 4210
+# - Wait for CLUSTER_DISCOVERY messages
+```
+
+#### Node Configuration
+SPORE nodes should send discovery messages periodically:
+```bash
+# Recommended: Send every 30-60 seconds
+# Message format: "CLUSTER_DISCOVERY"
+# Target: 255.255.255.255:4210
+```
+
+### 🌐 Discovery Endpoints
+
+#### Discovery Management
 - `GET /api/discovery/nodes` - View all discovered nodes and current status
 - `POST /api/discovery/refresh` - Manually trigger discovery refresh
 - `POST /api/discovery/primary/:ip` - Manually set a specific node as primary
 - `POST /api/discovery/random-primary` - Randomly select a new primary node
-- `GET /api/health` - Health check including discovery status
 
-### Testing Discovery
+#### Health Monitoring
+- `GET /api/health` - Comprehensive health check including discovery status
 
-Use the included test script to send discovery messages:
+### 🧪 Testing & Development
 
+#### Test Scripts
 ```bash
-# Send to broadcast address
+# Send discovery messages to test the system
 npm run test-discovery broadcast
 
 # Send to specific IP
@@ -90,28 +119,74 @@ npm run test-discovery broadcast 5
 
 # Test random primary node selection
 npm run test-random-selection
+
+# Monitor discovery in real-time
+npm run demo-discovery
 ```
 
-### Frontend Features
+#### Manual Testing
+```bash
+# Check discovery status
+curl http://localhost:3001/api/discovery/nodes
 
-The frontend now includes:
+# Check health
+curl http://localhost:3001/api/health
 
-- **Primary Node Display**: Shows the current primary node IP in the cluster header
-- **Random Selection**: Click the 🎲 button to randomly select a new primary node
-- **Real-time Updates**: Primary node display updates automatically every 10 seconds
-- **Visual Status Indicators**: Different colors and icons show node status
-- **Manual Refresh**: Users can manually trigger discovery updates
+# Manual refresh
+curl -X POST http://localhost:3001/api/discovery/refresh
 
-### Node Behavior
+# Random primary selection
+curl -X POST http://localhost:3001/api/discovery/random-primary
 
-- Nodes should send `CLUSTER_DISCOVERY` messages periodically (recommended: every 30-60 seconds)
-- The backend automatically cleans up stale nodes (not seen for 5+ minutes)
-- The most recently seen node becomes the primary connection
-- All API endpoints automatically use the discovered node IPs
+# Set specific primary
+curl -X POST http://localhost:3001/api/discovery/primary/192.168.1.100
+```
 
-### Configuration
+### 🔍 Troubleshooting
 
-- UDP Discovery Port: 4210 (configurable via `UDP_PORT` constant)
-- Discovery Message: `CLUSTER_DISCOVERY` (configurable via `DISCOVERY_MESSAGE` constant)
-- Stale Node Timeout: 5 minutes (configurable in `cleanupStaleNodes()` function)
-- Health Check Interval: 5 seconds (configurable in `setInterval`)
+#### Common Issues
+
+**No Nodes Discovered**
+```bash
+# Check if backend is running
+curl http://localhost:3001/api/health
+
+# Verify UDP port is open
+netstat -tulpn | grep 4210
+
+# Send test discovery message
+npm run test-discovery broadcast
+```
+
+**UDP Port Already in Use**
+```bash
+# Check for conflicting processes
+netstat -tulpn | grep 4210
+
+# Kill conflicting processes or change port in code
+# Restart backend server
+```
+
+**Client Not Initialized**
+```bash
+# Check discovery status
+curl http://localhost:3001/api/discovery/nodes
+
+# Verify nodes are sending discovery messages
+# Check network connectivity
+```
+
+#### Debug Commands
+```bash
+# Check discovery status
+curl http://localhost:3001/api/discovery/nodes
+
+# Check health
+curl http://localhost:3001/api/health
+
+# Manual refresh
+curl -X POST http://localhost:3001/api/discovery/refresh
+
+# Set primary node
+curl -X POST http://localhost:3001/api/discovery/primary/192.168.1.100
+```