feat: initial gateway implementation

README.md

@@ -0,0 +1,104 @@
+# SPORE Gateway
+
+A Go-based gateway service that replicates the functionality of the Node.js spore-ui server, providing UDP-based node discovery, cluster management, and HTTP API endpoints for SPORE devices.
+
+## Features
+
+- **UDP Node Discovery**: Listens for heartbeat messages from SPORE nodes on port 4210
+- **Cluster Management**: Tracks node status, manages primary node selection, and handles failover
+- **HTTP API Server**: Provides REST endpoints for cluster information, node management, and proxy calls
+- **WebSocket Server**: Real-time cluster updates via WebSocket connections
+- **Failover Logic**: Automatic switching between SPORE nodes when primary fails
+- **Proxy Functionality**: Generic proxy calls to SPORE node capabilities
+
+## Installation
+
+```bash
+go mod tidy
+go build
+```
+
+## Usage
+
+```bash
+./spore-gateway [options]
+
+Options:
+  -port string
+        HTTP server port (default "3001")
+  -udp-port string
+        UDP discovery port (default "4210")
+  -log-level string
+        Log level (debug, info, warn, error) (default "info")
+```
+
+## Integration
+
+The spore-gateway works together with the SPORE UI frontend:
+
+- **spore-gateway**: Runs on port 3001, handles UDP discovery, API endpoints, and WebSocket connections
+- **spore-ui**: Runs on port 3000, serves the frontend interface and connects to spore-gateway for all backend functionality
+
+Start spore-gateway first, then start the frontend:
+```bash
+# Terminal 1 - Start backend
+./spore-gateway
+
+# Terminal 2 - Start frontend
+cd ../spore-ui && npm start
+```
+
+Access the UI at: `http://localhost:3000`
+
+## API Endpoints
+
+### Discovery
+- `GET /api/discovery/nodes` - Get discovered nodes and cluster status
+- `POST /api/discovery/refresh` - Refresh cluster state
+- `POST /api/discovery/random-primary` - Select random primary node
+- `POST /api/discovery/primary/{ip}` - Set specific node as primary
+
+### Cluster
+- `GET /api/cluster/members` - Get cluster member information
+- `POST /api/cluster/refresh` - Trigger cluster refresh
+
+### Tasks
+- `GET /api/tasks/status` - Get task status (optionally for specific node)
+
+### Nodes
+- `GET /api/node/status` - Get system status
+- `GET /api/node/status/{ip}` - Get system status for specific node
+- `GET /api/node/endpoints` - Get available API endpoints
+- `POST /api/node/update` - Upload firmware to node
+
+### Proxy
+- `POST /api/proxy-call` - Make generic proxy call to SPORE node
+
+### Testing
+- `POST /api/test/websocket` - Test WebSocket broadcasting
+
+### Health
+- `GET /api/health` - Health check endpoint
+
+## WebSocket
+
+Connect to `/ws` for real-time cluster updates.
+
+## Development
+
+The application follows the same patterns as the original Node.js spore-ui server but is implemented in Go with:
+
+- Structured logging using logrus
+- Graceful shutdown handling
+- Concurrent-safe node management
+- HTTP middleware for CORS and logging
+- WebSocket support for real-time updates
+
+## Architecture
+
+- `main.go` - Application entry point
+- `internal/discovery/` - UDP-based node discovery
+- `internal/server/` - HTTP API server
+- `internal/websocket/` - WebSocket server for real-time updates
+- `pkg/client/` - SPORE API client
+- `pkg/config/` - Configuration management