reorg
This commit is contained in:
Raven Scott
@@ -0,0 +1,470 @@
|
||||
# Peer Visualize
|
||||
|
||||
Interactive real-time visualization of P2NS peer connections and system architecture.
|
||||
|
||||
## Overview
|
||||
|
||||
Peer Visualize is a P2NS plugin that provides a comprehensive, interactive dashboard for monitoring and visualizing your P2NS network. It offers real-time updates via WebSocket, multiple visualization modes, and detailed insights into peer connections, domains, and system metrics.
|
||||
|
||||
## Features
|
||||
|
||||
### Multiple Visualization Views
|
||||
|
||||
- **System Overview**: High-level dashboard with key metrics, charts, and statistics
|
||||
- **Network Graph**: Interactive force-directed or hierarchical graph of peer connections
|
||||
- **Peer Details**: Detailed list and information about all peers in the network
|
||||
- **Domain Map**: Visual representation of domains and their relationships to peers
|
||||
|
||||
### Real-Time Updates
|
||||
|
||||
- WebSocket-based real-time data streaming
|
||||
- Automatic updates every 5 seconds
|
||||
- Live connection status indicators
|
||||
- Instant reflection of network changes
|
||||
|
||||
### Interactive Visualizations
|
||||
|
||||
- **Force-Directed Graph**: Physics-based layout showing natural clustering of connected peers
|
||||
- **Hierarchical Graph**: Tree-based layout for structured network analysis
|
||||
- **Zoom & Pan**: Full D3.js zoom and pan support for exploring large networks
|
||||
- **Node Interaction**: Click nodes to view detailed information
|
||||
|
||||
### Advanced Filtering
|
||||
|
||||
- Filter by connection status (connected/disconnected peers)
|
||||
- Toggle domain visibility
|
||||
- Search peers and domains by name or ID
|
||||
- Show/hide offline peers (hierarchical layout)
|
||||
|
||||
### Metrics & Analytics
|
||||
|
||||
- Total peers seen
|
||||
- Currently connected peers
|
||||
- Total domains registered
|
||||
- Active connections count
|
||||
- System uptime tracking
|
||||
- Peer connection timeline charts
|
||||
- Connection duration distribution
|
||||
|
||||
## Installation
|
||||
|
||||
Peer Visualize is automatically available as an internal domain when P2NS is running. No additional installation is required.
|
||||
|
||||
## Access
|
||||
|
||||
Navigate to `https://peer.visualize` in your browser (or the configured internal domain URL).
|
||||
|
||||
## Usage
|
||||
|
||||
### System Overview
|
||||
|
||||
The default view provides a high-level dashboard with:
|
||||
|
||||
- **Metric Cards**: Key statistics at a glance
|
||||
- Total Peers Seen
|
||||
- Connected Peers
|
||||
- Total Domains
|
||||
- System Uptime
|
||||
- Active Connections
|
||||
|
||||
- **Charts**:
|
||||
- **Peer Connection Timeline**: Line chart showing peer connections over time
|
||||
- **Connection Duration Distribution**: Histogram of connection durations
|
||||
|
||||
### Network Graph
|
||||
|
||||
Visualize the network topology with interactive graphs:
|
||||
|
||||
1. **Select Layout**:
|
||||
- **Force-Directed**: Physics simulation showing natural clustering
|
||||
- **Hierarchical**: Tree structure with local node at root
|
||||
|
||||
2. **Interact with Nodes**:
|
||||
- Click on peer nodes to view detailed information
|
||||
- Click on domain nodes to see domain details
|
||||
- Drag nodes to reposition (force-directed layout)
|
||||
- Zoom and pan to explore large networks
|
||||
|
||||
3. **Filter Options**:
|
||||
- Toggle connected peers visibility
|
||||
- Toggle domains visibility
|
||||
- Search for specific peers or domains
|
||||
- Show offline peers (hierarchical layout only)
|
||||
|
||||
### Peer Details
|
||||
|
||||
View comprehensive information about all peers:
|
||||
|
||||
- Peer ID (full and truncated)
|
||||
- Connection status
|
||||
- Uptime duration
|
||||
- Local node indicator
|
||||
- Click any peer to open detailed side panel with:
|
||||
- Full peer ID
|
||||
- Connection metrics
|
||||
- Connection history
|
||||
- Last seen timestamp
|
||||
|
||||
### Domain Map
|
||||
|
||||
Visualize domain ownership and relationships:
|
||||
|
||||
- See which peers own which domains
|
||||
- View domain-to-peer connections
|
||||
- Filter by domain or peer
|
||||
- Interactive exploration of domain topology
|
||||
|
||||
## API Endpoints
|
||||
|
||||
The plugin exposes several REST API endpoints:
|
||||
|
||||
### `GET /api/system`
|
||||
Get complete system state including peers, domains, and metrics.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"peers": [...],
|
||||
"domains": [...],
|
||||
"localPeerId": "...",
|
||||
"peerChannels": [...],
|
||||
"metrics": {...},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/peers`
|
||||
Get detailed information about all peers.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"peers": [
|
||||
{
|
||||
"id": "...",
|
||||
"connected": true,
|
||||
"isLocal": false,
|
||||
"connectTime": 1234567890,
|
||||
"uptime": 3600000,
|
||||
"metrics": {...},
|
||||
"history": [...]
|
||||
}
|
||||
],
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/domains`
|
||||
Get all registered domains.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"domains": [
|
||||
{
|
||||
"domain": "example.tld",
|
||||
"hash": "hs://...",
|
||||
"consensus": {...}
|
||||
}
|
||||
],
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/topology`
|
||||
Get network topology data for graph rendering.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"id": "...",
|
||||
"type": "peer",
|
||||
"label": "...",
|
||||
"isLocal": true,
|
||||
"connected": true
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"source": "...",
|
||||
"target": "...",
|
||||
"type": "connection",
|
||||
"bidirectional": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/metrics`
|
||||
Get system-wide metrics.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"metrics": {
|
||||
"peers": {...},
|
||||
"domains": {...},
|
||||
"connections": {...}
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/peer/:peerId`
|
||||
Get detailed information for a specific peer.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "...",
|
||||
"connected": true,
|
||||
"connectTime": 1234567890,
|
||||
"uptime": 3600000,
|
||||
"metrics": {...},
|
||||
"history": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/domain/:domain`
|
||||
Get detailed information for a specific domain.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"domain": "example.tld",
|
||||
"hash": "hs://...",
|
||||
"consensus": {...},
|
||||
"clients": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## WebSocket API
|
||||
|
||||
The plugin provides real-time updates via WebSocket at `/ws`.
|
||||
|
||||
### Connection
|
||||
|
||||
Connect to `wss://peer.visualize/ws` (or `ws://` for non-HTTPS).
|
||||
|
||||
### Message Types
|
||||
|
||||
#### Client → Server
|
||||
|
||||
**Request System State:**
|
||||
```json
|
||||
{
|
||||
"type": "request-system"
|
||||
}
|
||||
```
|
||||
|
||||
**Request Topology:**
|
||||
```json
|
||||
{
|
||||
"type": "request-topology"
|
||||
}
|
||||
```
|
||||
|
||||
**Request Metrics:**
|
||||
```json
|
||||
{
|
||||
"type": "request-metrics"
|
||||
}
|
||||
```
|
||||
|
||||
#### Server → Client
|
||||
|
||||
**Initial State:**
|
||||
```json
|
||||
{
|
||||
"type": "init",
|
||||
"data": { /* system state */ },
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
**System Update:**
|
||||
```json
|
||||
{
|
||||
"type": "system-update",
|
||||
"data": { /* system state */ },
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
**Topology Update:**
|
||||
```json
|
||||
{
|
||||
"type": "topology-update",
|
||||
"data": { /* topology data */ },
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
**Metrics Update:**
|
||||
```json
|
||||
{
|
||||
"type": "metrics-update",
|
||||
"data": { /* metrics data */ },
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Backend (`index.js`)
|
||||
|
||||
The plugin handler provides:
|
||||
|
||||
- **HTTP Request Handler**: Serves static files and handles API endpoints
|
||||
- **WebSocket Server**: Real-time data streaming to connected clients
|
||||
- **Periodic Updates**: Automatic system state polling every 5 seconds
|
||||
- **Data Aggregation**: Combines data from multiple P2NS SDK sources
|
||||
|
||||
### Frontend
|
||||
|
||||
**Main Application (`app.js`)**:
|
||||
- View management and navigation
|
||||
- WebSocket client integration
|
||||
- Data flow coordination
|
||||
|
||||
**Visualization Components**:
|
||||
- `force-graph.js`: Force-directed graph using D3.js
|
||||
- `hierarchical.js`: Hierarchical tree layout
|
||||
- `domain-map.js`: Domain visualization
|
||||
- `dashboard.js`: Charts and metrics display
|
||||
- `peer-details.js`: Peer information display
|
||||
|
||||
**Supporting Modules**:
|
||||
- `data-processor.js`: Data transformation and processing
|
||||
- `websocket-client.js`: WebSocket connection management
|
||||
- `utils.js`: Utility functions
|
||||
|
||||
## Configuration
|
||||
|
||||
The plugin uses the standard P2NS plugin configuration in `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "peer.visualize",
|
||||
"version": "1.0.0",
|
||||
"domain": "peer.visualize",
|
||||
"description": "Interactive real-time visualization of P2NS peer connections and system architecture",
|
||||
"author": "P2NS",
|
||||
"homepage": "https://github.com/p2ns/p2ns",
|
||||
"license": "MIT",
|
||||
"dependencies": {},
|
||||
"www": "www"
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External Libraries
|
||||
|
||||
- **D3.js v7**: Graph visualization and force simulation
|
||||
- **Chart.js v4.4.0**: Charts and metrics visualization
|
||||
- **Tailwind CSS**: Styling framework
|
||||
|
||||
### P2NS SDK
|
||||
|
||||
The plugin uses the P2NS Plugin SDK to access:
|
||||
|
||||
- `sdk.state`: System state (peers, domains, metrics)
|
||||
- `sdk.domains`: Domain management and information
|
||||
- `sdk.peers`: Peer information and metrics
|
||||
- `sdk.metrics`: System metrics
|
||||
- `sdk.router`: HTTP request/response handling
|
||||
- `sdk.log`: Logging
|
||||
|
||||
## Browser Compatibility
|
||||
|
||||
- Modern browsers with ES6+ support
|
||||
- WebSocket support required
|
||||
- Canvas API for charts
|
||||
- SVG support for graphs
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **Update Frequency**: System updates are sent every 5 seconds. This can be adjusted in `index.js` if needed.
|
||||
- **Data Limits**: Peer history is limited to the last 50 entries per peer to prevent memory issues.
|
||||
- **Graph Rendering**: Large networks (100+ nodes) may experience reduced performance. Consider using filters to reduce visible nodes.
|
||||
- **WebSocket Connections**: Multiple browser tabs will each maintain a WebSocket connection.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### WebSocket Connection Issues
|
||||
|
||||
- **Status shows "Disconnected"**: Check browser console for WebSocket errors. Ensure the plugin is running and WebSocket server is initialized.
|
||||
- **No real-time updates**: Verify WebSocket connection in browser DevTools → Network → WS tab.
|
||||
|
||||
### Visualization Not Rendering
|
||||
|
||||
- **Graph appears empty**: Check browser console for JavaScript errors. Ensure D3.js is loaded.
|
||||
- **Charts not displaying**: Verify Chart.js is loaded and canvas elements are visible.
|
||||
|
||||
### Data Not Updating
|
||||
|
||||
- **Stale data**: Check that the plugin's `onInit()` completed successfully. View plugin logs in the admin interface.
|
||||
- **Missing peers/domains**: Verify P2NS is running and has active peers/domains. Check system state via `/api/system`.
|
||||
|
||||
### Performance Issues
|
||||
|
||||
- **Slow rendering**: Reduce visible nodes using filters. Close other browser tabs.
|
||||
- **High CPU usage**: Large networks may require more processing. Consider using hierarchical layout for better performance.
|
||||
|
||||
## Development
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
peer.visualize/
|
||||
├── config.json # Plugin configuration
|
||||
├── index.js # Plugin handler (backend)
|
||||
├── www/ # Frontend files
|
||||
│ ├── index.html # Main HTML
|
||||
│ ├── css/ # Stylesheets
|
||||
│ │ ├── style.css
|
||||
│ │ └── tailwind.css
|
||||
│ └── js/ # JavaScript modules
|
||||
│ ├── app.js # Main application
|
||||
│ ├── data-processor.js
|
||||
│ ├── websocket-client.js
|
||||
│ ├── utils.js
|
||||
│ └── visualization/ # Visualization components
|
||||
│ ├── dashboard.js
|
||||
│ ├── domain-map.js
|
||||
│ ├── force-graph.js
|
||||
│ ├── hierarchical.js
|
||||
│ └── peer-details.js
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### Modifying Update Frequency
|
||||
|
||||
Edit `index.js` and change the interval in `setupPeriodicUpdates()`:
|
||||
|
||||
```javascript
|
||||
updateInterval = setInterval(async () => {
|
||||
// ... update logic
|
||||
}, 5000); // Change 5000 to desired milliseconds
|
||||
```
|
||||
|
||||
### Adding New Views
|
||||
|
||||
1. Add view HTML to `index.html`
|
||||
2. Add view tab in sidebar
|
||||
3. Add view initialization in `app.js`
|
||||
4. Create visualization component if needed
|
||||
|
||||
### Customizing Visualizations
|
||||
|
||||
Each visualization component is self-contained:
|
||||
|
||||
- `ForceGraph`: Force-directed graph with D3.js
|
||||
- `HierarchicalGraph`: Tree layout visualization
|
||||
- `DomainMap`: Domain-specific visualization
|
||||
- `Dashboard`: Chart.js-based metrics
|
||||
|
||||
Modify the respective files to customize appearance or behavior.
|
||||
Reference in New Issue
Block a user