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

🚀 Quick Start Guide - RuVector Graph Explorer

5-Minute Setup

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Install the package
npm install ruvector-extensions

# Install peer dependencies for UI server
npm install express ws

# Install dev dependencies for TypeScript
npm install -D tsx @types/express @types/ws

Minimal Example

Create a file graph-ui.ts:

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

async function main() {
    // 1. Create database
    const db = new RuvectorCore({ dimension: 384 });

    // 2. Add sample data
    const sampleEmbedding = Array(384).fill(0).map(() => Math.random());
    await db.add('sample-1', sampleEmbedding, {
        label: 'My First Node',
        category: 'example'
    });

    // 3. Start UI server
    await startUIServer(db, 3000);

    console.log('🌐 Open http://localhost:3000 in your browser!');
}

main();

Run it:

npx tsx graph-ui.ts

Open your browser at http://localhost:3000

What You'll See

1. Interactive Graph - A force-directed visualization of your vectors
2. Search Bar - Filter nodes by ID or metadata
3. Metadata Panel - Click any node to see details
4. Controls - Zoom, pan, export, and more

Next Steps

Add More Data

// Generate 50 sample nodes
for (let i = 0; i < 50; i++) {
    const embedding = Array(384).fill(0).map(() => Math.random());
    await db.add(`node-${i}`, embedding, {
        label: `Node ${i}`,
        category: ['research', 'code', 'docs'][i % 3]
    });
}

Find Similar Nodes

1. Click any node in the graph
2. Click "Find Similar Nodes" button
3. Watch similar nodes highlight

Customize Colors

Edit src/ui/app.js:

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

Export Visualization

Click the PNG or SVG button in the header to save your graph.

Common Tasks

Real-time Updates

// Add nodes dynamically
setInterval(async () => {
    const embedding = Array(384).fill(0).map(() => Math.random());
    await db.add(`dynamic-${Date.now()}`, embedding, {
        label: 'Real-time Node',
        timestamp: Date.now()
    });

    // Notify UI
    server.notifyGraphUpdate();
}, 5000);

Search Nodes

Type in the search box to filter by:

• Node ID
• Metadata values
• Labels

Adjust Similarity

Use the Min Similarity slider to control which connections are shown:

• 0.0 = Show all connections
• 0.5 = Medium similarity (default)
• 0.8 = High similarity only

Keyboard Shortcuts

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

Mobile Support

The UI works great on mobile devices:

• Pinch to zoom
• Drag to pan
• Tap to select nodes
• Swipe to navigate

API Examples

REST API

# Get graph data
curl http://localhost:3000/api/graph

# Search nodes
curl http://localhost:3000/api/search?q=research

# Find similar
curl http://localhost:3000/api/similarity/node-1?threshold=0.5

# Get stats
curl http://localhost:3000/api/stats

WebSocket

const ws = new WebSocket('ws://localhost:3000');

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Received:', data);
};

// Subscribe to updates
ws.send(JSON.stringify({ type: 'subscribe' }));

Troubleshooting

Port Already in Use

# Use a different port
await startUIServer(db, 3001);

Graph Not Loading

# Check database has data
curl http://localhost:3000/api/stats

WebSocket Disconnected

• Check browser console for errors
• Verify firewall allows WebSocket connections
• Look for red status indicator in header

Full Example

See the complete example:

npm run example:ui

Next: Read the Full Guide

📚 Complete UI Guide

📖 API Reference

🎨 Customization Guide

---

Need help? Open an issue: https://github.com/ruvnet/ruvector/issues