p2ns/plugin-sites/peer.visualize/README.md

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:

{
  "peers": [...],
  "domains": [...],
  "localPeerId": "...",
  "peerChannels": [...],
  "metrics": {...},
  "timestamp": 1234567890
}

GET /api/peers

Get detailed information about all peers.

Response:

{
  "peers": [
    {
      "id": "...",
      "connected": true,
      "isLocal": false,
      "connectTime": 1234567890,
      "uptime": 3600000,
      "metrics": {...},
      "history": [...]
    }
  ],
  "timestamp": 1234567890
}

GET /api/domains

Get all registered domains.

Response:

{
  "domains": [
    {
      "domain": "example.tld",
      "hash": "hs://...",
      "consensus": {...}
    }
  ],
  "timestamp": 1234567890
}

GET /api/topology

Get network topology data for graph rendering.

Response:

{
  "nodes": [
    {
      "id": "...",
      "type": "peer",
      "label": "...",
      "isLocal": true,
      "connected": true
    }
  ],
  "edges": [
    {
      "source": "...",
      "target": "...",
      "type": "connection",
      "bidirectional": true
    }
  ]
}

GET /api/metrics

Get system-wide metrics.

Response:

{
  "metrics": {
    "peers": {...},
    "domains": {...},
    "connections": {...}
  },
  "timestamp": 1234567890
}

GET /api/peer/:peerId

Get detailed information for a specific peer.

Response:

{
  "id": "...",
  "connected": true,
  "connectTime": 1234567890,
  "uptime": 3600000,
  "metrics": {...},
  "history": [...]
}

GET /api/domain/:domain

Get detailed information for a specific domain.

Response:

{
  "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:

{
  "type": "request-system"
}

Request Topology:

{
  "type": "request-topology"
}

Request Metrics:

{
  "type": "request-metrics"
}

Server → Client

Initial State:

{
  "type": "init",
  "data": { /* system state */ },
  "timestamp": 1234567890
}

System Update:

{
  "type": "system-update",
  "data": { /* system state */ },
  "timestamp": 1234567890
}

Topology Update:

{
  "type": "topology-update",
  "data": { /* topology data */ },
  "timestamp": 1234567890
}

Metrics Update:

{
  "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:

{
  "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():

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.