ruvector/npm/packages/ruvector-extensions/docs/UI_GUIDE.md

RuVector Graph Explorer UI Guide

Overview

The RuVector Graph Explorer is an interactive web-based UI for visualizing and exploring vector embeddings as a force-directed graph. Built with D3.js, it provides real-time updates, similarity queries, and comprehensive graph exploration tools.

Features

🎨 Visualization

• Force-directed graph layout - Nodes naturally cluster based on similarity
• Interactive node dragging - Reposition nodes by dragging
• Zoom and pan - Navigate large graphs with mouse/touch gestures
• Responsive design - Works seamlessly on desktop, tablet, and mobile

🔍 Search & Filter

• Node search - Find nodes by ID or metadata content
• Similarity queries - Click nodes to find similar vectors
• Threshold filtering - Adjust minimum similarity for connections
• Max nodes limit - Control graph density for performance

📊 Data Exploration

• Metadata panel - View detailed information for selected nodes
• Statistics display - Real-time node and edge counts
• Color coding - Visual categorization by metadata
• Link weights - Edge thickness represents similarity strength

💾 Export

• PNG export - Save visualizations as raster images
• SVG export - Export as scalable vector graphics
• High quality - Preserves graph layout and styling

⚡ Real-time Updates

• WebSocket integration - Live graph updates
• Connection status - Visual indicator of server connection
• Toast notifications - User-friendly feedback

Quick Start

1. Installation

npm install ruvector-extensions

2. Basic Usage

import { RuvectorCore } from 'ruvector-core';
import { startUIServer } from 'ruvector-extensions/ui-server';

// Initialize database
const db = new RuvectorCore({ dimension: 384 });

// Add some vectors
await db.add('doc1', embedding1, { label: 'Document 1', category: 'research' });
await db.add('doc2', embedding2, { label: 'Document 2', category: 'code' });

// Start UI server
const server = await startUIServer(db, 3000);

// Open browser at http://localhost:3000

3. Run Example

cd packages/ruvector-extensions
npm run example:ui

Then open your browser at http://localhost:3000

UI Components

Header

• Title - Application branding
• Export buttons - PNG and SVG export
• Reset view - Return to default zoom/pan
• Connection status - WebSocket connection indicator

Sidebar

Search & Filter Section

• Search input - Type to filter nodes by ID or metadata
• Clear button - Reset search results
• Similarity slider - Adjust minimum similarity threshold (0-1)
• Max nodes input - Limit displayed nodes (10-1000)
• Apply filters - Refresh graph with new settings

Statistics Section

• Nodes count - Total visible nodes
• Edges count - Total visible connections
• Selected node - Currently selected node ID

Metadata Panel (when node selected)

• Node details - ID and metadata key-value pairs
• Find similar - Query for similar nodes
• Close button - Hide metadata panel

Graph Canvas

• Main visualization - Force-directed graph
• Zoom controls - +/- buttons and fit-to-view
• Loading overlay - Progress indicator during operations

Interactions

Mouse/Touch Controls

Action	Result
Click node	Select and show metadata
Double-click node	Find similar nodes
Drag node	Reposition node
Scroll/pinch	Zoom in/out
Drag background	Pan view
Click background	Deselect node

Keyboard Shortcuts

Key	Action
+	Zoom in
-	Zoom out
0	Reset view
F	Fit to view
Esc	Clear selection

API Endpoints

REST API

// Get graph data
GET /api/graph?max=100

// Search nodes
GET /api/search?q=query

// Find similar nodes
GET /api/similarity/:nodeId?threshold=0.5&limit=10

// Get node details
GET /api/nodes/:nodeId

// Add new node
POST /api/nodes
{
  "id": "node-123",
  "embedding": [0.1, 0.2, ...],
  "metadata": { "label": "Example" }
}

// Get statistics
GET /api/stats

// Health check
GET /health

WebSocket Messages

Client → Server

// Subscribe to updates
{
  "type": "subscribe"
}

// Request graph data
{
  "type": "request_graph",
  "maxNodes": 100
}

// Similarity query
{
  "type": "similarity_query",
  "nodeId": "node-123",
  "threshold": 0.5,
  "limit": 10
}

Server → Client

// Connection established
{
  "type": "connected",
  "message": "Connected to RuVector UI Server"
}

// Graph data update
{
  "type": "graph_data",
  "payload": {
    "nodes": [...],
    "links": [...]
  }
}

// Node added
{
  "type": "node_added",
  "payload": { "id": "node-123", "metadata": {...} }
}

// Similarity results
{
  "type": "similarity_result",
  "payload": {
    "nodeId": "node-123",
    "similar": [...]
  }
}

Customization

Node Colors

Edit app.js to customize node colors:

getNodeColor(node) {
    if (node.metadata && node.metadata.category) {
        const colors = {
            'research': '#667eea',
            'code': '#f093fb',
            'documentation': '#4caf50',
            'test': '#ff9800'
        };
        return colors[node.metadata.category] || '#667eea';
    }
    return '#667eea';
}

Styling

Edit styles.css to customize appearance:

:root {
    --primary-color: #667eea;
    --secondary-color: #764ba2;
    --accent-color: #f093fb;
    /* ... more variables ... */
}

Force Layout

Adjust force simulation parameters in app.js:

this.simulation = d3.forceSimulation()
    .force('link', d3.forceLink().distance(100))
    .force('charge', d3.forceManyBody().strength(-300))
    .force('center', d3.forceCenter(width / 2, height / 2))
    .force('collision', d3.forceCollide().radius(30));

Performance Optimization

For Large Graphs (1000+ nodes)

1. Limit visible nodes

   const maxNodes = 500; // Reduce from default 1000
   

2. Reduce force iterations

   this.simulation.alpha(0.5).alphaDecay(0.05);
   

3. Disable labels for small nodes

   label.style('display', d => this.zoom.scale() > 1.5 ? 'block' : 'none');
   

4. Use clustering

   • Group similar nodes before rendering
   • Show clusters as single nodes
   • Expand on demand

Mobile Optimization

The UI is already optimized for mobile:

• Touch gestures for zoom/pan
• Responsive sidebar layout
• Simplified controls on small screens
• Efficient rendering with requestAnimationFrame

Troubleshooting

Graph not loading

• Check browser console for errors
• Verify database has vectors: GET /api/stats
• Ensure WebSocket connection: look for green dot in header

Slow performance

• Reduce max nodes in sidebar
• Clear search/filters
• Restart simulation with fewer iterations
• Check network tab for slow API calls

WebSocket disconnections

• Check firewall/proxy settings
• Verify port 3000 is accessible
• Look for server errors in terminal

Export not working

• Ensure browser allows downloads
• Try different export format (PNG vs SVG)
• Check browser compatibility (Chrome/Firefox recommended)

Browser Support

Browser	Version	Support
Chrome	90+	✅ Full
Firefox	88+	✅ Full
Safari	14+	✅ Full
Edge	90+	✅ Full
Mobile Safari	14+	✅ Full
Chrome Mobile	90+	✅ Full

Advanced Usage

Custom Server Configuration

import express from 'express';
import { UIServer } from 'ruvector-extensions/ui-server';

const app = express();
const server = new UIServer(db, 3000);

// Add custom middleware
app.use('/api/custom', customRouter);

// Start with custom configuration
await server.start();

Real-time Notifications

// Notify clients of graph updates
server.notifyGraphUpdate();

// Broadcast custom message
server.broadcast({
    type: 'custom_event',
    payload: { message: 'Hello!' }
});

Integration with Existing Apps

// Use as middleware
app.use('/graph', server.app);

// Or mount on custom route
const uiRouter = express.Router();
uiRouter.use(server.app);
app.use('/visualize', uiRouter);

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Support

• 📖 Documentation: https://github.com/ruvnet/ruvector
• 🐛 Issues: https://github.com/ruvnet/ruvector/issues
• 💬 Discussions: https://github.com/ruvnet/ruvector/discussions