Observatory (3D Visualization)

Real-time 3D visualization of your agent network

Observatory is NeuAIs’ flagship visualization tool - a beautiful, interactive 3D interface for monitoring and managing your entire agent infrastructure.

Overview

Observatory provides real-time visibility into:

• Agents - All AI agents with status, metrics, and connections
• Services - Backend microservices (Auth, Compute, Storage, etc.)
• Infrastructure - Databases, caches, service registries
• Connections - Live data flows between components
• Metrics - CPU, memory, network I/O for all components

Quick Start

Access Observatory

Local Development:

cd neuais.com/hub.neuais.com/observatory.neuais.com
python3 -m http.server 3000

Open: http://localhost:3000/start.html

Production:
Access at: https://observatory.neuais.com

First Time User Flow

1. Landing Page - See the welcome screen with animated starfield
2. Click “Launch Observatory” - Enter the 3D visualization
3. Explore - Drag to rotate, scroll to zoom, click nodes for details
4. Dock - Hover at bottom to reveal tools and cards
5. Customize - Change colors, shapes, and visual preferences

Interface Elements

Top Menu Bar

View Menu:

• Show Filters
• Show Overview
• Show Metrics
• Full Screen

Window Menu:

• Minimize All Cards
• Restore All Cards
• Close All Cards

Help Menu:

• Documentation
• Keyboard Shortcuts
• About Observatory

Bottom Dock (Auto-Hide)

Hover at the bottom of the screen to reveal:

3D Visualization

Node Types:

• ● Spheres - Services (blue/purple)
• ■ Cubes - AI Agents (yellow/green)
• ◆ Diamonds - Infrastructure (orange/red)

Interactions:

• Drag - Rotate 3D view
• Scroll - Zoom in/out
• Click Node - Show details card
• Right-Click - Context menu (coming soon)

Visual Effects:

• Pulsing Nodes - Active components breathe/glow
• Particle Flows - Data moving between nodes
• Connection Lines - Relationships between components
• Status Colors - Green (active), Grey (idle), Red (error)

Features

Visual Customization

Access: Dock → Customize Card

Options:

• Color Mode - By category or by type
• Color Picker - Custom colors for each component type
• Shape Selection - Sphere, Cube, Diamond, Pyramid, Torus
• Presets - Save and load custom themes
• Persistence - Settings saved in browser localStorage

Default Color Scheme:

Filtering & Visibility

Access: Dock → Filters Card

Toggle Options:

• ☑ Show Agents
• ☑ Show Services
• ☑ Show Infrastructure
• ☑ Particle Flows
• ☑ Auto-Rotation

Hide categories to focus on specific parts of your system.

Metrics & Monitoring

Access: Dock → Metrics Card

Live Metrics:

• Avg CPU Usage - Across all components
• Total Memory - Current RAM usage
• Network I/O - Data transfer rate
• Active Connections - Between nodes
• Uptime - System uptime

Updates every 5 seconds (configurable).

Node Details

Click any node to see:

• Name - Component identifier
• Status - Active, Idle, Starting, Error
• Type - Agent, Service, Infrastructure
• ID - Unique identifier
• Metadata - Language, template, environment
• Resources - CPU %, Memory usage
• Connections - List of connected components
• Actions - Start, Stop, View Logs, View Code

System Overview

Access: Dock → Overview Card

Statistics:

• Total Agents (count)
• Total Services (count)
• Infrastructure Components (count)
• Active Components (count)
• Health Score (percentage)

Topology View

Access: Dock → Topology Card

Shows:

• Key connection paths (e.g., SMO → RIC)
• Database connection counts
• Cache usage patterns
• Agent-to-service mappings

Terminal Access

Access: Dock → Terminal Card

Features:

• Execute commands in Observatory context
• View command history
• Auto-completion
• Multi-line input

Available Commands:

help              # Show all commands
status            # System status
agents            # List all agents
services          # List all services
start <id>        # Start component
stop <id>         # Stop component
restart <id>      # Restart component
logs <id>         # View logs
clear             # Clear terminal

Keyboard Shortcuts

Configuration

Visual Settings

Quality Presets:

• High - Maximum detail, all effects (default)
• Medium - Balanced performance
• Low - Minimal effects, better FPS

Adjustable:

• Particle Count (1-10)
• Zoom Speed (1-10)
• Rotation Speed (1-10)
• Node Detail Level

Data Source

Static Data (Development):
Uses js/observatory-data.js with predefined agents/services

Live API (Production):
Connects to WebSocket at ws://localhost:8080/ws for real-time updates

Browser Support

Recommended:

• Chrome 90+ ✅
• Firefox 88+ ✅
• Edge 90+ ✅
• Safari 14+ ⚠️ (limited WebGL support)

Requirements:

• WebGL 2.0 support
• Modern JavaScript (ES2020+)
• localStorage enabled
• Minimum 1280x720 resolution

Architecture

Technology Stack

Frontend:

• Three.js - 3D rendering engine
• Vanilla JavaScript - No framework dependencies
• CSS3 - Glass morphism, animations
• WebGL 2.0 - Hardware-accelerated graphics

Data Layer:

• Static - js/observatory-data.js (development)
• Dynamic - WebSocket API (production)
• Storage - localStorage for preferences

File Structure

observatory.neuais.com/
├── index.html              # Main application
├── start.html              # Landing page
├── css/
│   ├── observatory-base.css    # Core styles, menu
│   ├── observatory-cards.css   # Floating cards
│   ├── observatory-dock.css    # Auto-hide dock
│   └── observatory-glass.css   # Glass effects
├── js/
│   ├── observatory-core.js         # Three.js scene
│   ├── observatory-data.js         # Data definitions
│   ├── observatory-visual-config.js # Color/shape config
│   ├── observatory-dock.js         # Dock system
│   ├── observatory-cards.js        # Card management
│   ├── observatory-menu.js         # Menu bar
│   ├── observatory-context-menu.js # Right-click
│   ├── card-templates.js           # Card HTML
│   └── observatory-terminal-commands.js # Terminal
├── 3d/
│   └── skateboard/
│       └── three.min.js    # Three.js library
└── assets/
    ├── logo.png            # NeuAIs logo
    └── icons/              # UI icons (25 PNG files)

Data Model

Agent/Service Object:

{
  id: 'anomaly-detector',
  name: 'Anomaly Detector',
  status: 'active',          // active, idle, starting, error
  cpu: 12,                   // CPU usage %
  mem: '24MB',               // Memory usage
  connections: ['metrics-api', 'redis-cache']  // Connected IDs
}

Connection: Inferred from connections array. Particles flow from source to target along curved Bézier paths.

Rendering Pipeline

1. Load Data - From static file or API
2. Create Nodes - Position in 3D clusters
3. Apply Visual Config - Colors, shapes from user prefs
4. Create Particles - Flow animations between connections
5. Animation Loop - 60 FPS updates (pulsing, particles)
6. User Interactions - Click, hover, drag handlers

Performance

Optimization

For 100+ Nodes:

• Node clustering by category
• Instanced meshes for identical shapes
• Particle count limit (5 per connection)
• LOD (Level of Detail) for distant nodes

For 1000+ Nodes:

• Reduce sphere segments (16 → 8)
• Disable particle flows
• Use simpler shapes (cubes only)
• Implement frustum culling

Metrics

Current Performance:

• 31 nodes + 150 particles = 60 FPS (Chrome, M1 MacBook)
• 100 nodes + 500 particles = 45 FPS
• 1000 nodes (no particles) = 30 FPS

Memory Usage:

• Initial load: ~50MB
• With all cards open: ~80MB
• After 1 hour: ~120MB (stable)

Troubleshooting

Issue: Blank Screen

Causes:

• WebGL not supported
• JavaScript errors
• Missing Three.js library

Solutions:

1. Check browser console (F12)
2. Verify Three.js loaded: typeof THREE
3. Try different browser (Chrome recommended)
4. Disable browser extensions

Issue: Low FPS

Causes:

• Too many nodes/particles
• Integrated graphics
• Other tabs open

Solutions:

1. Open Settings card → Lower quality
2. Open Filters → Disable particles
3. Reduce particle count slider
4. Close other browser tabs

Issue: Nodes Not Visible

Causes:

• Filters disabled category
• Nodes positioned off-screen
• Data not loaded

Solutions:

1. Open Filters → Enable all categories
2. Reset view (refresh page)
3. Check console for data errors

Issue: Cards Not Opening

Causes:

• JavaScript error
• Card system not initialized
• Event listener issue

Solutions:

1. Check console for errors
2. Refresh page
3. Try different dock icon

Issue: Customization Not Saving

Causes:

• localStorage disabled
• Private browsing mode
• Storage quota exceeded

Solutions:

1. Enable localStorage in browser settings
2. Exit private/incognito mode
3. Clear old data: localStorage.clear()

API Integration

WebSocket Protocol

Connect:

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

ws.onopen = () => {
  console.log('Connected to Observatory API');
};

Subscribe to Updates:

ws.send(JSON.stringify({
  type: 'subscribe',
  categories: ['agents', 'services', 'infrastructure']
}));

Receive Updates:

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  // Update visualization with new data
};

REST API

Get All Agents:

GET /api/v1/agents

Get Agent Details:

GET /api/v1/agents/{id}

Start Agent:

POST /api/v1/agents/{id}/start

Stop Agent:

POST /api/v1/agents/{id}/stop

Future Enhancements

Planned Features

Q1 2026:

• ✨ VR mode (WebXR support)
• 🎮 Gamepad navigation
• 🔊 Audio feedback (spatial audio)
• 📱 Mobile-optimized UI

Q2 2026:

• 🌐 Multi-cluster view
• 📊 Historical playback
• 🎥 Record and export animations
• 🤖 AI-powered insights

Q3 2026:

• 🔗 Direct code editing integration
• 📡 Real-time collaboration
• 🎨 Custom themes marketplace
• 📈 Advanced analytics

Community Requests

Vote on features: github.com/neuais/observatory/discussions

Support

Documentation:

• Quick Start
• API Reference
• Architecture

Community:

• GitHub Issues: github.com/neuais/observatory/issues
• Discussions: github.com/neuais/observatory/discussions

Contact:

• Email: support@neuais.com
• Twitter: @neuais

Next: Platform Architecture →