feat: add topology view

docs/TOPOLOGY_VIEW.md

@@ -0,0 +1,146 @@
+# Topology View - Network Topology Visualization
+
+## Overview
+
+The Topology view provides an interactive, force-directed graph visualization of the SPORE cluster network topology. It displays each cluster member as a node and shows the connections (links) between them with latency information.
+
+## Features
+
+### 🎯 **Interactive Network Graph**
+- **Force-directed layout**: Nodes automatically arrange themselves based on connections
+- **Zoom and pan**: Navigate through large network topologies
+- **Drag and drop**: Reposition nodes manually for better visualization
+- **Responsive design**: Adapts to different screen sizes
+
+### 📊 **Node Information**
+- **Status indicators**: Color-coded nodes based on member status (ACTIVE, INACTIVE, DEAD)
+- **Hostname display**: Shows the human-readable name of each node
+- **IP addresses**: Displays the network address of each member
+- **Resource information**: Access to system resources and capabilities
+
+### 🔗 **Connection Visualization**
+- **Latency display**: Shows network latency between connected nodes
+- **Color-coded links**: Different colors indicate latency ranges:
+  - 🟢 Green: ≤5ms (excellent)
+  - 🟠 Orange: 6-15ms (good)
+  - 🔴 Red-orange: 16-30ms (fair)
+  - 🔴 Red: >30ms (poor)
+- **Bidirectional connections**: Shows actual network topology from each node's perspective
+
+### 🎨 **Visual Enhancements**
+- **Legend**: Explains node status colors and latency ranges
+- **Hover effects**: Interactive feedback when hovering over nodes and links
+- **Selection highlighting**: Click nodes to select and highlight them
+- **Smooth animations**: Force simulation provides natural movement
+
+## Technical Implementation
+
+### Architecture
+- **ViewModel**: `TopologyViewModel` manages data and state
+- **Component**: `TopologyGraphComponent` handles rendering and interactions
+- **Framework**: Integrates with the existing SPORE UI framework
+- **Library**: Uses D3.js v7 for graph visualization
+
+### Data Flow
+1. **Primary node query**: Fetches cluster members from the primary node
+2. **Individual node queries**: Gets cluster view from each member node
+3. **Topology building**: Constructs network graph from actual connections
+4. **Fallback mesh**: Creates basic mesh if no actual connections found
+
+### API Endpoints
+- `/api/cluster/members` - Get cluster membership from primary node
+- `/api/cluster/members?ip={nodeIP}` - Get cluster view from specific node
+
+## Usage
+
+### Navigation
+1. Click the "🌐 Topology" tab in the main navigation
+2. The view automatically loads and displays the network topology
+3. Use the refresh button to update the visualization
+
+### Interaction
+- **Zoom**: Use mouse wheel or pinch gestures
+- **Pan**: Click and drag on empty space
+- **Select nodes**: Click on any node to highlight it
+- **Move nodes**: Drag nodes to reposition them
+- **Hover**: Hover over nodes and links for additional information
+
+### Refresh
+- Click the "Refresh" button to reload network topology data
+- Useful after network changes or when adding/removing nodes
+
+## Configuration
+
+### Graph Parameters
+- **Node spacing**: 120px between connected nodes
+- **Repulsion force**: -400 strength for node separation
+- **Collision radius**: 40px minimum distance between nodes
+- **Zoom limits**: 0.1x to 4x zoom range
+
+### Visual Settings
+- **Node sizes**: Vary based on status (ACTIVE: 10px, INACTIVE: 8px, DEAD: 6px)
+- **Link thickness**: Proportional to latency (2-8px range)
+- **Colors**: Semantic color scheme for status and latency
+
+## Troubleshooting
+
+### Common Issues
+
+#### No Graph Displayed
+- Check browser console for JavaScript errors
+- Verify D3.js library is loading correctly
+- Ensure cluster has discovered nodes
+
+#### Missing Connections
+- Verify nodes are responding to API calls
+- Check network connectivity between nodes
+- Review cluster discovery configuration
+
+#### Performance Issues
+- Reduce number of displayed nodes
+- Adjust force simulation parameters
+- Use zoom to focus on specific areas
+
+### Debug Information
+- Test file available at `test-topology-view.html`
+- Console logging provides detailed component lifecycle information
+- Network topology data is logged during updates
+
+## Future Enhancements
+
+### Planned Features
+- **Real-time updates**: WebSocket integration for live topology changes
+- **Metrics overlay**: CPU, memory, and network usage display
+- **Path finding**: Show routes between specific nodes
+- **Export options**: Save graph as image or data file
+- **Custom layouts**: Alternative visualization algorithms
+
+### Performance Optimizations
+- **Lazy loading**: Load node details on demand
+- **Virtualization**: Handle large numbers of nodes efficiently
+- **Caching**: Store topology data locally
+- **Web Workers**: Offload computation to background threads
+
+## Dependencies
+
+- **D3.js v7**: Force-directed graph visualization
+- **SPORE UI Framework**: Component architecture and state management
+- **Modern Browser**: ES6+ support required
+- **Network Access**: Ability to reach cluster nodes
+
+## Browser Support
+
+- **Chrome**: 80+ (recommended)
+- **Firefox**: 75+
+- **Safari**: 13+
+- **Edge**: 80+
+
+## Contributing
+
+To contribute to the Members view:
+
+1. Follow the existing code style and patterns
+2. Test with different cluster configurations
+3. Ensure responsive design works on mobile devices
+4. Add appropriate error handling and logging
+5. Update documentation for new features