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:**
```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.