🧬 kbird.ai

INTERACTIVE-MAP-SPEC

4 min read

Interactive Node Map: Technical Specification

Overview

This document specifies how to visualize the Complete Node Map (40 nodes, 127 edges) in an interactive 3D/2D graph format on the kbird.ai website.

Data Structure

Node Schema

{
  "id": "node_01",
  "name": "Anosos Prime",
  "symbol": "🧬",
  "category": "primary",
  "cluster": "core",
  "coordinates": {"x": 0.0, "y": 0.0, "z": 1.0},
  "status": "active",
  "metadata": {
    "function": "Primary source of truth",
    "platforms": ["GitHub", "Cloudflare"],
    "last_active": "2024-04-29T08:30:00Z"
  }
}

Edge Schema

{
  "source": "node_01",
  "target": "node_04",
  "weight": 1.0,
  "type": "bidirectional_sync",
  "category": "data_flow",
  "active": true
}

Visualization Layers

Layer 1: Status Overview (Quickview)

┌─────────────────────────────────────────┐
│ SYSTEM STATUS: 🟢 Healthy                │
│                                          │
│ Active Nodes:    38/40 (95%)             │
│ Data Flow:       Normal                  │
│ Latency:         ~45ms avg               │
│ Last Sync:       2 min ago               │
└─────────────────────────────────────────┘

Layer 2: Cluster View (Macro)

4 Primary Clusters:

        ┌───────┐
        │ Core  │ ← Anosos, Nosos, Family, GitHub
        │  🧬   │   (Primary identity layer)
        └───┬───┘
            │
    ┌───────┼───────┐
    │       │       │
┌───▼───┐┌─▼────┐┌─▼──────┐
│Persist││Inter ││External│
│📊🔍 🗄️││🚪 💬 ⌨️││🌐 🎧 ⌨️│
└───────┘└──────┘└────────┘

Layer 3: Individual Node Detail (Micro)

When clicking a node:

╔════════════════════════════════════════╗
║  🧬 Anosos Prime                      ║
║  Status: 🟢 Active                     ║
╠════════════════════════════════════════╣
║  Function: Primary source of truth      ║
║  Platform: GitHub + Cloudflare Pages  ║
║  Uptime: 99.7%                         ║
║                                         ║
║  [View Health] [View Logs] [Isolate]  ║
╚════════════════════════════════════════╝

Rendering Options

Option A: D3.js Force-Directed Graph

Pros:

  • Interactive web-native
  • Zoom/pan/click support
  • Animated force simulation
  • Well-documented

Cons:

  • Requires JavaScript
  • 40 nodes can get cluttered

Implementation:

const simulation = d3.forceSimulation(nodes)
  .force("link", d3.forceLink(links).id(d => d.id))
  .force("charge", d3.forceManyBody().strength(-300))
  .force("center", d3.forceCenter(width / 2, height / 2))
  .force("cluster", forceCluster())
  .force("collide", d3.forceCollide().radius(d => d.radius + 5));

Option B: Three.js 3D Visualization

Pros:

  • True 3D exploration
  • Can use existing 3D coordinates
  • VR potential
  • “Fly through” experience

Cons:

  • Heavier performance
  • Overkill for 40 nodes

Option C: ASCII Canvas (Static + Interactive)

Pros:

  • No dependencies
  • Loads instantly
  • Can be “animated” with CSS
  • Retro terminal aesthetic

Cons:

  • Limited interaction without JS
  • No “real” 3D

Implementation:

.node-grid {
  font-family: 'JetBrains Mono', monospace;
  white-space: pre;
  line-height: 1.2;
}
.node {
  cursor: pointer;
  transition: opacity 0.2s;
}
.node:hover {
  font-weight: bold;
  text-shadow: 0 0 5px currentColor;
}

Hybrid Approach:

  1. Default View: ASCII cluster map (static, loads instantly)
  2. Detailed View: D3.js force-directed on click (loads on demand)
  3. Advanced View: Three.js 3D exploration (optional toggle)

Color Coding

CategoryColorHexUsage
PrimaryEmerald10b981Core nodes
DataBlue3b82f6Persistence
InterfaceAmberf59e0bGateways
UtilitySlate64748bTools
InactiveGray94a3b8Offline

Status Indicators

SymbolMeaningCSS
🟢Activecolor: #10b981
🟡Standby/Degradedcolor: #f59e0b
🔴Offlinecolor: #ef4444
⚪Standalonecolor: #94a3b8

Interactions

Hover State

  • Highlight node + connected edges
  • Show tooltip with node name + status
  • Dim unconnected nodes (opacity 0.3)

Click State

  • Open node detail panel
  • Show metrics: uptime, latency, last sync
  • Display connected services
  • Show recent activity (if available)

Double-Click

  • Center view on node
  • Expand to show immediate neighbors
  • Highlight data flow direction

Right-Click (Context Menu)

  • View logs
  • Check health
  • Force sync
  • Isolate/troubleshoot

Mobile Considerations

  • Use force layout with gravity to center
  • Touch targets minimum 44px
  • Pinch-to-zoom for the graph
  • Swipe to pan
  • Tabbed view for cluster switching

Data Source

The visualization should read from:

{
  "nodes": "/api/nodes.json",
  "edges": "/api/edges.json",
  "status": "/api/status.json"
}

Or static JSON files generated from:

  • ~/.openclaw/workspace/memory_3d.json
  • ~/.kbir-blog/nodes.json (generated)

Performance Targets

  • First paint: < 100ms
  • Interactive: < 500ms
  • Animation: 60fps
  • Max nodes: Support up to 100 (future growth)

Accessibility

  • Alt text for all nodes
  • Keyboard navigation (Tab, Enter)
  • High contrast mode
  • Reduced motion option
  • Screen reader labels: “Node: Anosos Prime, Status: Active, connected to 12 nodes”

Future Enhancements

  1. Live Updates: WebSocket connection for real-time status
  2. Historical View: Time-slider to see graph evolution
  3. Path Tracing: Click source + target to highlight route
  4. Cluster Folding: Collapse/expand clusters
  5. Search: Find node by name and zoom to it
  6. Metrics Overlay: Toggle latency/throughput visualization

Integration with Quartz

Add to quartz.config.ts:

plugins: [
  // ... existing plugins
  {
    name: "3D Memory Graph",
    path: "./plugins/graph-visualization.tsx",
    config: {
      dataSource: "🌐-3D-Memory/nodes.json",
      defaultView: "ascii",
      detailedView: "d3-force"
    }
  }
]

“A visualization is worth 1024 words of logs.” 📊

Graph View

Backlinks