spore-ui/docs/TOPOLOGY_VIEW.md

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