AIngle DAG Visualization

Real-time interactive visualization of the AIngle Distributed Acyclic Graph (DAG) with advanced filtering, timeline views, and export capabilities.

Features

Core Visualization

• Real-time Updates: WebSocket-based live updates of DAG changes
• Interactive Graph: D3.js-powered force-directed graph with zoom, pan, and drag
• Neural Network Style: Organic physics simulation for natural clustering
• Node Types: Support for Genesis, Entry, Action, Link, Agent, and System nodes
• Edge Visualization: Directional edges with type-based coloring

Advanced Filtering

• Type Filters: Filter by node type (Genesis, Entry, Action, Link, Agent)
• Agent Filters: Show/hide nodes by agent with color coding
• Date Range: Filter entries by timestamp range
• Content Search: Full-text search across node IDs, labels, and content
• Quick Filters: Preset filter combinations (Recent, Genesis Only, etc.)

Timeline View

• Chronological Visualization: Bar chart view of entries over time
• Temporal Zoom: Switch between day, week, month, and year views
• Interactive Bars: Click to see detailed breakdown by time period
• Type Breakdown: See distribution of node types per time bucket

Export Functionality

• SVG Export: Vector graphics with embedded styles
• PNG Export: High-resolution raster images (2x scale)
• JSON Export: Complete DAG data with metadata
• CSV Export: Node data in spreadsheet format
• Batch Export: Export all formats at once

Real-time Notifications

• Toast Notifications: Non-intrusive popups for events
• Sound Alerts: Optional audio feedback (customizable)
• Badge Counter: Unread notification count in title bar
• Event Types: Node added, edge added, connection status

Performance Optimizations

• Virtualization: Render only visible nodes for large graphs (>1000 nodes)
• Lazy Loading: On-demand loading of node details
• Render Queue: Batched DOM updates with requestIdleCallback
• Auto-optimization: Automatic performance tuning based on FPS
• Progressive Loading: Incremental data loading for initial state

Responsive Design

• Mobile-friendly: Touch gestures, collapsible sidebar
• Tablet Support: Optimized layouts for mid-size screens
• Desktop: Full-featured interface with multi-panel layout
• Print Support: Clean printable views
• Accessibility: High contrast mode, reduced motion support

Architecture

Backend (Rust + Axum)

aingle_viz/
├── src/
│   ├── lib.rs          # Library entry point
│   ├── main.rs         # Binary entry point
│   ├── api.rs          # REST API endpoints
│   ├── dag.rs          # DAG data structures
│   ├── events.rs       # WebSocket event system
│   ├── error.rs        # Error types
│   └── server.rs       # HTTP server configuration

Frontend (JavaScript + D3.js)

web/
├── index.html          # Original simple interface
├── index-enhanced.html # Full-featured interface
├── css/
│   └── style.css       # Responsive styles
├── js/
│   ├── app.js          # Original app logic
│   ├── dag-graph.js    # D3.js graph visualization
│   ├── timeline.js     # Timeline view
│   ├── filters.js      # Advanced filtering
│   ├── export.js       # Export functionality
│   ├── notifications.js# Notification system
│   ├── performance.js  # Performance optimizations
│   └── websocket.js    # WebSocket client
└── assets/
    ├── logo.svg
    └── favicon.ico

API Endpoints

REST API

Get DAG Data

GET /api/dag
GET /api/dag/d3

Query parameters:

• limit: Maximum number of nodes to return
• node_type: Filter by node type
• author: Filter by author/agent

Get Specific Entry

GET /api/dag/entry/:hash

Get Agent Entries

GET /api/dag/agent/:id

Get Recent Entries

GET /api/dag/recent?n=100

Get Statistics

GET /api/stats

Create Node (Testing)

POST /api/node
Content-Type: application/json

{
  "id": "node-id",
  "label": "Node Label",
  "node_type": "entry",
  "author": "agent-id"
}

WebSocket

Connect to /ws/updates for real-time updates.

Messages from server:

{
  "type": "initial_state",
  "data": {
    "nodes": [...],
    "edges": [...]
  }
}

{
  "type": "node_added",
  "node": {...},
  "edges": [...]
}

{
  "type": "edge_added",
  "edge": {...}
}

Messages to server:

{
  "type": "ping"
}

Usage

Starting the Server

# Development mode
cargo run --bin aingle_viz

# Production mode
cargo run --release --bin aingle_viz

The server starts on http://localhost:8080 by default.

Environment Variables

# Server configuration
VIZ_HOST=127.0.0.1
VIZ_PORT=8080

Using the Interface

Basic Navigation

1. Zoom: Mouse wheel or pinch gesture
2. Pan: Click and drag on empty space
3. Select Node: Click on a node to view details
4. Drag Node: Click and drag a node to reposition

Filtering

1. Open the sidebar (click ☰ on mobile)
2. Use type checkboxes to show/hide node types
3. Click agent colors to filter by agent
4. Set date range for temporal filtering
5. Use search box for content search

Timeline View

1. Click "Show Timeline" button
2. Select zoom level (Day/Week/Month/Year)
3. Click bars to see breakdown
4. Switch back with "Show DAG" button

Exporting

1. Click export button for desired format
2. File downloads automatically
3. Use "Export All" for batch export

Development

Building

# Build the project
cargo build

# Build with optimizations
cargo build --release

# Run tests
cargo test

# Generate documentation
cargo doc --open

Frontend Development

The frontend uses vanilla JavaScript with D3.js. No build step required.

# Serve static files during development
# The Rust server includes static file serving
cargo run

Adding New Features

Adding a New Filter Type

1. Update filters.js:

filterManager.addCustomFilter('myFilter', (node) => {
    return /* your filter logic */;
});

2. Add UI controls in HTML
3. Wire up event handlers

Adding New Export Formats

1. Extend export.js:

async exportMyFormat(filename = null) {
    // Your export logic
}

2. Add button to UI
3. Connect to ExportManager instance

Performance Guidelines

For Large Graphs (>1000 nodes)

1. Enable Virtualization: Automatically enabled when node count exceeds threshold
2. Reduce Simulation Strength: Lower force calculations
3. Hide Labels: Small nodes don't need labels
4. Use Filtering: Focus on subset of data

Memory Management

• Clear caches periodically with performanceOptimizer.clearCache()
• Use lazy loading for node details
• Enable progressive loading for initial data

Browser Support

• Chrome/Edge: ✅ Full support
• Firefox: ✅ Full support
• Safari: ✅ Full support
• Mobile Safari: ✅ Touch gestures supported
• Mobile Chrome: ✅ Touch gestures supported

Required Browser Features

• ES6+ JavaScript
• WebSocket API
• D3.js v7 compatibility
• SVG support
• Canvas API (for PNG export)

Troubleshooting

WebSocket Connection Failed

• Check server is running
• Verify firewall settings
• Ensure WebSocket protocol matches (ws/wss)

Performance Issues

• Enable virtualization for large graphs
• Reduce visible nodes with filters
• Pause simulation when not needed
• Clear cache if memory usage is high

Export Not Working

• Check browser allows downloads
• Verify SVG is properly rendered
• For PNG export, ensure canvas is supported

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

[Add license information]

Credits

• Built with D3.js
• Server powered by Axum
• Part of the AIngle project

Screenshots

Main DAG View

Timeline View

Filtering Interface

Mobile View

Roadmap

• WebGL rendering for ultra-large graphs
• 3D visualization mode
• Graph diff visualization
• Collaborative filtering
• Custom color schemes
• Animation replay
• Graph metrics dashboard
• Plugin system

Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation
• Review API examples

Version: 1.0.0 Last Updated: 2025-12-17