Observatory Visual Customization

Overview

Users can customize how the Observatory displays their system architecture through colors, shapes, and visual preferences.

Features

1. Legend Card

Access: Dock → Legend

Shows complete visual guide:

• Component categories and colors
• Status indicators (active, stopped, starting)
• Connection types and colors
• Shape meanings

Dynamic: Updates based on user customization.

2. Shape Differentiation

Different 3D shapes for different component types:

• ◆ Diamond (octahedron) - Databases (PostgreSQL, Redis)
• ▲ Pyramid (tetrahedron) - Service registries (Consul, Yggdrasil)
• ■ Cube - AI agents (all types)
• ● Sphere - API services (HTTP, gRPC)
• ◯ Torus - Edge services (Cloudflare Workers)

Accessibility: Shape + color helps colorblind users differentiate components.

3. Connection Styling

Particles between nodes are color-coded by connection type:

• Blue - HTTP API calls (medium speed)
• Purple - gRPC high-performance (faster)
• Red - Database queries (slower, larger particles)
• Amber - Cache access (very fast, smaller particles)
• Emerald - Message queue
• Cyan - Service discovery/registry

Connection type is inferred from manifest dependencies or node types.

4. Type-Based Coloring

Each component type has a unique default color:

Infrastructure:

• PostgreSQL: Blue
• Redis: Red
• Consul: Purple
• Yggdrasil: Cyan

Services:

• Auth: Emerald
• Compute: Purple
• Storage: Amber
• SMO: Blue
• RIC: Indigo

Agents:

• RIC-integrated: Green
• Worker: Yellow
• Batch: Purple
• Streaming: Cyan

5. Customization Panel

Access: Dock → Customize

Users can:

• Toggle between “Color by Category” and “Color by Type”
• Pick custom colors for each type (color picker)
• Choose shapes for each type (dropdown)
• Preview changes in real-time
• Save preferences
• Reset to defaults

6. Persistent Configuration

Storage: localStorage Persistence: Survives browser restarts Scope: Per-user, per-browser

Users’ visual preferences are automatically saved and restored on next visit.

User Workflow

Viewing the Legend

1. Hover bottom of screen
2. Dock appears
3. Click “Legend” icon
4. Floating card shows complete visual guide

Customizing Visuals

1. Hover bottom of screen
2. Click “Customize” in dock
3. Choose mode (by Category or by Type)
4. Adjust colors and shapes for each type
5. Click “Save & Apply”
6. Visualization rebuilds with new scheme

Resetting to Defaults

1. Open Customize panel
2. Click “Reset to Default”
3. Confirm prompt
4. Visualization returns to original scheme

Technical Architecture

Configuration Object

{
  mode: 'type',  // 'type' or 'category'
  types: {
    'postgres': {
      color: '#3b82f6',
      shape: 'octahedron',
      label: 'PostgreSQL'
    }
  },
  categories: {
    'infrastructure': { 
      color: '#ef4444', 
      shape: 'octahedron' 
    }
  }
}

Files

Core Logic:

• js/observatory-visual-config.js - Configuration management

UI Components:

• js/observatory-cards.js - Legend and customize cards
• js/observatory-dock.js - Dock items for legend and customize

Rendering:

• index-live.html - Node creation with shapes/colors
• css/observatory-cards.css - Legend and customize styles

Integration Points

Node Creation:

• Queries observatoryVisualConfig for color/shape
• Falls back to built-in TYPE_COLORS and SHAPE_MAP

Particle Creation:

• Uses CONNECTION_STYLES for particle appearance
• Based on inferred connection type

Legend Generation:

• Dynamically generated from current config
• Shows actual colors/shapes in use

Default Visual Scheme

Node Colors (Type Mode)

Infrastructure:

• PostgreSQL: #3b82f6 (Blue)
• Redis: #ef4444 (Red)
• Consul: #8b5cf6 (Purple)

Services:

• Auth: #10b981 (Emerald)
• SMO: #3b82f6 (Blue)
• RIC: #6366f1 (Indigo)

Agents:

• RIC-integrated: #22c55e (Green)
• Worker: #facc15 (Yellow)
• Batch: #a855f7 (Purple)

Node Shapes

Infrastructure:

• Databases: Octahedron (diamond)
• Registries: Tetrahedron (pyramid)

Services:

• HTTP/gRPC: Sphere
• Edge: Torus

Agents:

• All types: Cube

Connection Colors

• HTTP: #3b82f6 (Blue)
• gRPC: #8b5cf6 (Purple)
• Database: #ef4444 (Red)
• Cache: #f59e0b (Amber)
• Queue: #10b981 (Emerald)
• Registry: #06b6d4 (Cyan)

Status Indicators

• Active: Bright, glowing, full opacity
• Stopped/Idle: Grey (#666666), dim, 60% opacity
• Starting: Pulsing yellow animation

Performance

Shape Complexity (Vertices)

• Tetrahedron: ~12 vertices (lightest)
• Octahedron: ~24 vertices (light)
• Cube: ~24 vertices (light)
• Sphere (16 segments): ~289 vertices (medium)
• Torus: ~512+ vertices (heavy)

Recommendation: Use torus sparingly for special nodes only.

Optimization Strategies

For large systems (100+ nodes):

1. Reduce sphere segments to 8-16
2. Use InstancedMesh for nodes with same shape+color
3. Implement LOD (Level of Detail) for distant nodes
4. Limit particle count per connection

Future Enhancements

Preset Themes

• Database-focus (highlight databases, dim others)
• AI-focus (highlight agents, dim services)
• Colorblind-safe (high contrast, distinct shapes)

Export/Import

• Export config as JSON
• Share with team
• Version control for visual layouts

Advanced Filtering

• Click legend item → Highlight matching nodes
• Search by type → Auto-highlight
• Hide categories temporarily

Mini Preview

• Live 3D preview in customization panel
• See changes before applying
• A/B comparison mode

Troubleshooting

Colors not changing:

• Check browser console for errors
• Verify localStorage is enabled
• Try “Reset to Default” then re-customize

Shapes not rendering:

• Some shapes (torus) are GPU-intensive
• Reduce complexity for older hardware
• Check Three.js console warnings

Settings not persisting:

• Check localStorage quota
• Clear old data: localStorage.clear()
• Try different browser

Performance issues:

• Reduce torus usage (heavy geometry)
• Lower sphere segment count
• Disable particle flows temporarily (Filters card)

API Integration

WebSocket Command (future):

ws.send({
  type: 'update_visual_config',
  config: visualConfig
});

Team Sync (future):

• Save config to backend
• Sync across team members
• Organization-wide defaults