Architecture

Dashboard & Telemetry

🖥️ Dashboard & Telemetry#

Next-Level Dashboard Architecture#

Frontend: Svelte 5 (Vite) + TailwindCSS Backend: Node.js (Express) + Socket.IO State: Redis (hot data) + SQLite (history) Visuals: Chart.js + xterm.js

Real-Time Architecture (Socket.IO)#

Server pushes events to rooms — zero polling:

// Server: emit to specific bot room
io.to(`bot:${botName}`).emit('log', {
  timestamp: Date.now(), level: 'INFO',
  message: 'Creeper detected at [100, 64, -200]'
});

// Server: broadcast global stats
io.emit('stats:global', { tps: 19.98, ram: '4.2GB' });

// Client: join bot room
socket.emit('join', 'bot:Groqqo');
socket.on('log', (data) => terminal.writeln(data.message));

UI/UX Principles#

  1. Dark Mode Only: #0a0a0a background, #00ff9d neon green accents
  2. Monospace Fonts: JetBrains Mono or Fira Code for data precision
  3. High Density: “Mission Control” — see EVERYTHING, no whitespace
  4. Micro-Interactions: Hover effects, subtle glows, live counters

Visualization Patterns#

Data Type Visualization Library
TPS / RAM Real-time Line Chart (Streaming) Chart.js
Bot Health Circular Progress / Health Bar CSS / SVG
World Map Interactive 2D/3D Embed Prismarine Viewer (iframe)
Console Scrollable Terminal Window xterm.js
Inventory Grid of Icons (hover details) HTML/CSS Grid

Genius Features#

  • Command Palette (Ctrl+K): Quick access to bot commands (!come, !stop)
  • Toast Notifications: Non-intrusive alerts for errors/deaths
  • Multi-View: Split screen to watch 4 bots at once
  • Replay System: Scrub through past logs/metrics (Redis/DB storage)

JSONL Bot Event Schema#

Structured event format replacing ad-hoc string parsing:

{"v":1,"ts":"2026-04-04T03:15:00.000Z","agent":"Groqqo","type":"command","data":{"command":"!newAction","raw":"Generated response: !newAction(...)"}}
{"v":1,"ts":"2026-04-04T03:15:01.000Z","agent":"Groqqo","type":"cost","data":{"model":"openai/gpt-oss-120b","prompt":1200,"completion":350}}
{"v":1,"ts":"2026-04-04T03:15:02.000Z","agent":"Groqqo","type":"death","data":{"cause":"lava","position":[100,12,-200]}}

Fields#

Field Type Description
v 1 Schema version
ts ISO 8601 Event timestamp
agent string Bot name (Minecraft username)
type enum Event type
data object Type-specific payload

Event Types#

Type Trigger Data Fields
command Generated response: ! command, raw
message Sending message: raw
cost [COST] model=... model, prompt, completion
death death strings cause, raw
error error (case-insensitive) raw
innovation !newAction or Strategy raw
line catch-all raw

Analytics & Metrics#

Tracked in tools/analyzer.js:

  • Innovation Index: How many new strategies did the swarm invent?
  • Cooperation Efficiency: Tasks completed / Total Messages
  • Betrayal Rate: Frequency of broken contracts
  • Global: totalMessages, totalCommands, totalErrors, innovationScore

Upgrade Path: Behavioral Fingerprinting# 

class StrategyProfiler {
  analyzeDecision(bot, prompt, response, reasoning) {
    const signature = {
      riskTolerance: this.assessRisk(response),
      planningDepth: this.countSteps(reasoning),
      novelty: this.isNovel(response)
    };
    this.profiles[bot].update(signature);
  }
}

Enables papers like “GPT-4 vs Gemini Decision-Making in Minecraft” 🎓

Observatory Upgrade Roadmap#

Current State → Apex Goal#

Tension Current Apex
Polling vs. Streaming File polling every 2-5s Sub-100ms WebSocket push
Files vs. Database history.json + log scraping Redis + TimescaleDB
Monolith vs. Microservices Single dashboard.js API Gateway + Metrics Engine + Log Aggregator
Observation vs. Analysis Shows what happened Reveals why (decision trees, strategy patterns)
4 Bots vs. 100 Bots Hardcoded agent names Dynamic agent registry

Critical Fixes Applied#

  1. Dashboard WebSocket: Fixed let is Connected → let isConnected (syntax error)
  2. Viewer Kick Loop: Set enforce-secure-profile=false in server.properties
  3. Network Config: Standardized internal=localhost, external=0.0.0.0

Prismarine Viewer#

Architecture# 

viewer.js (Node) ──mineflayerViewer(bot, {port})──▶ Express + Socket.IO
                                                        │
                                                        ▼
                                              Browser: Three.js + WebGL workers
                                              WorldView: loadChunk() → toJson() → worker

Version Compatibility Layer#

Server runs 1.21.11 but prismarine-viewer supports up to 1.21.4:

Proxy(bot) → version: "1.21.4" (renderVersion)
           → world.getColumnAt() → column.toJson() → remapChunkJsonPalette()
                palette stateIds: 1.21.11 space → 1.21.4 space
           → bot.on('blockUpdate') → remapped stateId

Env overrides: VIEWER_RENDER_VERSION, VIEWER_VERSION_FALLBACK=false

Viewer Config# 

PORT=55669                        # web server port
VIEWER_USERNAME=Spectator         # bot login name
VIEWER_VIEW_DISTANCE=8            # chunk radius
VIEWER_RECONNECT_BASE_MS=5000     # reconnect start delay
VIEWER_RECONNECT_MAX_MS=60000     # reconnect cap
VIEWER_RECONNECT_JITTER_MS=1500   # random jitter
VIEWER_INITIAL_CONNECT_JITTER_MS=2000
VIEWER_RECONNECT_DUPLICATE_MS=30000  # duplicate login wait

Reconnect Strategy#

Exponential backoff: min(base × 2^attempts, max) + random(jitter) Duplicate login: fixed 30s wait (not exponential) Version mismatch kick: auto-fallback to version: auto