docs: The Forge refinement addendum — Chronicler #80

Technical gaps addressed: - Mapped all data sources to existing API endpoints - Event bus architecture with normalized event format - Asset pipeline: 3 options ranked by feasibility - PixiJS recommendation over raw Canvas/WebGL - Concrete coordinate system for realm layout - Bezier curve connection routing spec - Performance budget for 24/7 wall display - Camera preset system with durations - Sound design layers - Hosting/deployment recommendation (no new hardware Phase 1) - Phase 1 MVP stripped to achievable weekend scope - 5 targeted questions for Gemini consultation Complements The Reconciler's vision spec with implementation skeleton.
2026-04-11 22:33:04 +00:00
parent c8a854bfd7
commit 6495be2b68
1 changed files with 404 additions and 0 deletions
--- a/docs/tasks/task-127-the-forge-living-art/REFINEMENT-ADDENDUM.md
+++ b/docs/tasks/task-127-the-forge-living-art/REFINEMENT-ADDENDUM.md
@@ -0,0 +1,404 @@
+# The Forge — Refinement Addendum
+
+**Author:** Chronicler #80  
+**Date:** April 11, 2026  
+**Purpose:** Tighten gaps in the original spec, add technical specifics grounded in existing infrastructure, and flag decisions needed before Phase 1
+
+---
+
+## 1. DATA ARCHITECTURE — What Actually Exists Today
+
+The original spec lists data sources but doesn't map them to concrete APIs. Here's what's real right now:
+
+### Already Built & Working
+
+| Data Source | Endpoint | What It Gives Us |
+|------------|----------|-----------------|
+| **Infrastructure Module** | `GET /admin/infrastructure` | All 8 server health (RAM, disk, CPU, uptime, load, restart status), game server list from Pterodactyl |
+| **Infrastructure Refresh** | `GET /admin/infrastructure/refresh` | Force-refresh cache, returns full fleet JSON |
+| **Server Detail** | `GET /admin/infrastructure/server/:id` | Per-server detail + game servers on that node |
+| **Trinity Core** | `POST https://mcp.firefrostgaming.com/exec` | SSH command execution to any of 7 servers |
+| **Pterodactyl API** | Panel VPS `/api/application/servers` | Game server list, node assignments, RAM/disk allocations, suspended status |
+| **Stripe Webhooks** | `POST /stripe/webhook` | `checkout.session.completed`, subscription events |
+| **MCP Logs** | `/admin/mcp-logs` | All Trinity Core command executions logged to Arbiter |
+| **Uptime Kuma** | `status.firefrostgaming.com` | 34 monitors with Discord webhooks |
+
+### Needs to Be Built for The Forge
+
+| Data Source | What's Missing | Complexity |
+|------------|---------------|-----------|
+| **Real-time event stream** | Arbiter has no WebSocket server — all current admin is HTMX request/response | Medium — needs new Express WS endpoint |
+| **Payment event broadcasting** | Stripe webhook handler processes payments but doesn't broadcast to connected clients | Low — add emit after existing handler |
+| **Discord message events** | Bot processes commands but doesn't expose message activity as a stream | Medium — need new event listener |
+| **Git push events** | Gitea webhooks aren't configured to notify Arbiter | Low — Gitea supports webhook POST |
+| **Player join/leave events** | Pterodactyl has no event API — would need polling or Wings websocket | High — significant new integration |
+| **Trinity member identification** | No way to know WHO ran an SSH command (all go through root) | Low — Trinity Core logs include server+command, can infer |
+
+### The Critical Gap: Event Bus
+
+The Forge needs a **real-time event bus** — something that collects events from all sources and pushes them to connected Forge clients via WebSocket.
+
+**Proposed architecture:**
+
+```
+Stripe webhook ──┐
+Discord events ──┤
+Gitea webhooks ──┼──► Arbiter Event Bus ──► WebSocket ──► Forge Client
+MCP command log ─┤       (in-memory)
+Uptime Kuma ─────┘
+```
+
+This is a new Arbiter module: `src/services/forgeBus.js`
+
+It collects events, normalizes them to a common format, and pushes to WebSocket subscribers. Simple in-memory — no database persistence needed for real-time visualization events.
+
+**Event format:**
+
+```json
+{
+  "type": "payment|discord|git|ssh|player|health",
+  "source": "stripe|discord|gitea|trinity-core|pterodactyl|uptime-kuma",
+  "server": "command-center|tx1-dallas|...",
+  "timestamp": "2026-04-11T22:30:00Z",
+  "data": { ... },
+  "visual": {
+    "from": "stripe-kingdom",
+    "to": "command-center",
+    "particle": "gold-coin",
+    "effect": "confetti"
+  }
+}
+```
+
+The `visual` field is key — it tells the Forge renderer exactly what animation to play without the frontend needing to understand business logic.
+
+---
+
+## 2. ASSET PIPELINE — The Unanswered Question
+
+The original spec calls for illustrated city/tower designs, 30-40 district icons, character figurines, and external territory art. But it doesn't say **how these get created.**
+
+### Options (ranked by feasibility)
+
+**Option A: AI-Generated + Human Refined (Recommended for Phase 2)**
+- Use Gemini/DALL-E/Midjourney to generate base illustrations
+- Michael or commissioned artist refines and unifies style
+- Export as transparent PNGs at 2x target resolution
+- Pros: Fast iteration, low cost
+- Cons: Style consistency requires curation effort
+
+**Option B: Commissioned Artist**
+- Find artist on Fiverr/ArtStation who does fantasy game UI
+- Provide the concept art as style reference
+- Commission full asset pack (cities, districts, icons, figurines)
+- Pros: Professional consistency, unique style
+- Cons: Cost ($500-2000+), turnaround time, iteration cycles
+
+**Option C: Procedural/Code-Generated (Phase 1 only)**
+- Generate geometric representations in canvas/WebGL
+- Glowing circles, hexagonal tiles, particle systems
+- No external art assets needed
+- Pros: Immediate, no dependencies
+- Cons: Won't look like "wall art" until replaced
+
+**Recommended path:**
+- **Phase 1:** Option C — geometric/procedural, prove the concept
+- **Phase 2:** Option A — AI-generate base assets, refine the best ones
+- **Phase 3+:** Option B if budget allows — commission the hero pieces (Command Center tower, Fire/Frost forges)
+
+### Asset Inventory (what needs to exist)
+
+| Category | Count | Phase |
+|----------|-------|-------|
+| Server cities/towers | 8 | Phase 2 |
+| Service district buildings | ~35 | Phase 2-3 |
+| Game server village markers | ~14 | Phase 2 |
+| External territory landmarks | 5 (Cloudflare, Stripe, Discord, Website, Claude) | Phase 2 |
+| Trinity figurines | 3 + Jack | Phase 2 |
+| Particle sprites | ~8 types (fire, frost, arcane, gold, data, health, warning, critical) | Phase 1 (simple) / Phase 2 (illustrated) |
+| Background/terrain | 1 large illustrated backdrop | Phase 2 |
+| UI overlays (Active Mode) | ~5-10 panel designs | Phase 4 |
+
+---
+
+## 3. RENDERING DECISIONS — Canvas 2D vs WebGL
+
+The spec says "Canvas 2D for MVP, maybe upgrade to WebGL." This needs a firmer decision.
+
+### Canvas 2D (Recommended for ALL phases)
+
+**Why Canvas 2D wins here:**
+- The Forge is fundamentally a 2D illustrated scene with particle effects on top
+- Canvas 2D handles hundreds of animated particles at 60fps easily
+- Image compositing (pre-rendered city illustrations + live overlays) is Canvas 2D's sweet spot
+- No 3D geometry needed — this isn't a flythrough, it's a painting that breathes
+- Simpler development, easier debugging, better browser compatibility
+- Pi 5 can handle Canvas 2D without breaking a sweat
+
+**When WebGL would matter:**
+- If you wanted 3D camera rotation (but the spec describes fixed viewpoints with slow pans)
+- If particle counts exceeded thousands (unlikely for infrastructure events)
+- If you wanted real-time lighting/shadows (the illustrated style doesn't need this)
+
+**Recommendation:** Commit to Canvas 2D with a good particle system library. Consider [PixiJS](https://pixijs.com/) — it's a 2D renderer that uses WebGL under the hood for performance but exposes a 2D API. Best of both worlds.
+
+### PixiJS Specifically
+
+- Handles sprite sheets, particle systems, filters (glow, blur), blend modes
+- Perfect for "illustrated background + animated overlays" architecture
+- Runs on WebGL with Canvas 2D fallback
+- Active community, well-documented
+- Free and open source
+
+---
+
+## 4. LAYOUT SYSTEM — Hardcoded vs Dynamic
+
+The spec implies a hand-placed layout (cities at fixed positions). This is actually the right call for Phase 1-3, but needs to be explicit:
+
+### Coordinate System
+
+**Proposal:** 1920×1080 base resolution, scale to display
+
+```javascript
+const REALM_LAYOUT = {
+  'command-center': { x: 960, y: 400, scale: 1.2 },  // Center, slightly large
+  'tx1-dallas':     { x: 350, y: 350, scale: 1.0 },   // Left (Fire side)
+  'nc1-charlotte':  { x: 1570, y: 350, scale: 1.0 },  // Right (Frost side)
+  'panel-vps':      { x: 960, y: 200, scale: 0.8 },   // Between Fire & Frost, above
+  'wiki-vps':       { x: 1400, y: 650, scale: 0.7 },   // Knowledge sector
+  'services-vps':   { x: 520, y: 650, scale: 0.6 },    // Communications sector
+  'dev-panel':      { x: 200, y: 700, scale: 0.5 },    // Edge, experimental
+  'trinity-core':   { x: 960, y: 750, scale: 0.6 },    // Near bottom, near Trinity
+
+  // External territories (edges/corners)
+  'cloudflare':     { x: 960, y: 50, scale: 0.8 },     // Top center (sky/clouds)
+  'stripe':         { x: 1750, y: 100, scale: 0.6 },   // Top right
+  'discord':        { x: 170, y: 100, scale: 0.6 },    // Top left
+  'claude':         { x: 960, y: 30, scale: 0.5 },     // Above everything
+  'website':        { x: 1750, y: 500, scale: 0.5 },   // Right side
+
+  // Convergence point
+  'convergence':    { x: 960, y: 850 },                 // Bottom center
+  'trinity-figures': { x: 960, y: 920 }                 // Base of realm
+};
+```
+
+This gives the spec's vision a concrete coordinate system. Fire on the left, Frost on the right, Command Center in the middle, Cloudflare raining down from above, Trinity watching from below.
+
+---
+
+## 5. CONNECTION ROUTING — Bezier Curves, Not Straight Lines
+
+The spec describes "highways" but doesn't specify how they render. For fantasy aesthetic:
+
+**Every connection should be a Bezier curve** with configurable control points:
+
+```javascript
+const CONNECTIONS = [
+  {
+    id: 'cloudflare-to-command',
+    from: 'cloudflare', to: 'command-center',
+    type: 'external',
+    color: '#FF6B35',
+    particleType: 'data-droplet',
+    // Bezier control points for the "waterfall cascade" effect
+    curve: [
+      { x: 960, y: 50 },    // start (Cloudflare)
+      { x: 900, y: 150 },   // control 1 (slight left drift)
+      { x: 1020, y: 300 },  // control 2 (slight right drift)
+      { x: 960, y: 400 }    // end (Command Center)
+    ],
+    width: 3,               // base width
+    flowSpeed: 2,            // particles per second (ambient)
+    intensityMultiplier: true // wider when more traffic
+  },
+  // ... more connections
+];
+```
+
+Particles flow along these curves. The curves themselves can be invisible (just particle paths) or drawn as faint glowing lines — configurable per connection type.
+
+---
+
+## 6. PERFORMANCE BUDGET
+
+Missing from original spec. Critical for 24/7 wall display:
+
+| Metric | Target | Hard Limit |
+|--------|--------|-----------|
+| Frame rate | 60 FPS | Never below 30 FPS |
+| Memory usage | < 200MB | < 500MB |
+| CPU usage (idle) | < 15% | < 30% |
+| CPU usage (active events) | < 30% | < 50% |
+| Network (WebSocket) | < 1KB/s average | < 10KB/s burst |
+| Reconnect time | < 5 seconds | < 30 seconds |
+| Crash recovery | Auto-restart browser | < 60 seconds to full display |
+
+### Auto-Recovery (critical for 24/7)
+
+```bash
+# Kiosk mode launcher script
+#!/bin/bash
+while true; do
+  chromium-browser \
+    --kiosk \
+    --disable-restore-session-state \
+    --disable-translate \
+    --noerrdialogs \
+    --no-first-run \
+    --disable-infobars \
+    "https://forge.firefrostgaming.com"
+  
+  # If browser crashes, wait 5 seconds and restart
+  sleep 5
+done
+```
+
+The Forge web app itself should detect WebSocket disconnection and show a subtle "reconnecting" frost effect over the realm rather than an error screen.
+
+---
+
+## 7. AMBIENT MODE CAMERA — More Specific
+
+The spec says "cycles viewing angles" but needs specifics:
+
+### Camera Presets (automatic rotation)
+
+| View | Duration | Description |
+|------|----------|-------------|
+| **Realm Overview** | 60s | Full realm visible, default "postcard" view |
+| **Fire Side Focus** | 30s | Slow pan to TX1 and its villages |
+| **Frost Side Focus** | 30s | Slow pan to NC1 and its villages |
+| **Command Center Close** | 20s | Zoom into central spire, districts visible |
+| **Highway Traffic** | 20s | Follow a particle from Cloudflare to Command Center |
+| **Convergence** | 15s | Zoom to Trinity figures and convergence point |
+
+**Event interrupt:** When a significant event occurs (payment, alert), camera smoothly follows the particle to its destination, then returns to cycle.
+
+**Transition:** All camera movements use easeInOutCubic — no linear pans, no jarring cuts.
+
+---
+
+## 8. SOUND DESIGN — Optional But Specified
+
+The spec mentions "optional ambient soundtrack" but should be more specific if we build it:
+
+### Sound Layers
+
+| Layer | Trigger | Sound |
+|-------|---------|-------|
+| **Ambient base** | Always | Soft crackling fire + distant wind + subtle magical hum |
+| **Payment** | Stripe event | Crystalline chime + coin drop |
+| **Player join** | Pterodactyl event | Soft "whoosh" + village bell |
+| **Alert** | Uptime Kuma warning | Low mystical tone (not jarring) |
+| **Critical** | Server offline | Deeper tone, subtle alarm |
+| **SSH command** | Trinity Core event | Arcane zap (very subtle) |
+
+**Volume:** All sounds at conversation-background level. The Forge should enhance a room, not dominate it.
+
+**Mute:** Hardware mute button or time-of-day auto-mute (e.g., silent 10 PM - 7 AM).
+
+---
+
+## 9. HOSTING & DEPLOYMENT — Where Does The Forge Live?
+
+The spec lists hardware options but doesn't decide. Recommendation:
+
+### Phase 1: Command Center hosted, any browser client
+
+- Forge frontend: static files served from Command Center (or Cloudflare Pages)
+- Forge backend: new WebSocket endpoint in Arbiter
+- Client: any browser in kiosk mode
+- **No new hardware needed for Phase 1**
+
+### Phase 2+: Dedicated display
+
+- Raspberry Pi 5 (4GB) behind monitor
+- Chromium kiosk mode
+- Auto-start on boot, auto-recover on crash
+- WiFi or ethernet to home network
+- Cost: ~$80 (Pi 5 + case + power + SD card)
+
+### URL Structure
+
+- `forge.firefrostgaming.com` — The Forge display (Cloudflare Pages)
+- `discord-bot.firefrostgaming.com/api/forge/events` — WebSocket event stream
+- `discord-bot.firefrostgaming.com/api/forge/state` — Current realm state (REST)
+
+---
+
+## 10. QUESTIONS FOR GEMINI
+
+These are the architectural questions worth getting Gemini's perspective on:
+
+1. **PixiJS vs raw Canvas 2D vs Three.js** — For a 2D illustrated scene with particle overlays running 24/7, which renderer gives best performance/quality tradeoff on a Pi 5?
+
+2. **Event bus architecture** — In-memory event bus in Arbiter vs dedicated event service (Redis pub/sub, SSE stream)? What scales better for a single-client visualization?
+
+3. **Asset pipeline** — For ~60 illustrated fantasy assets that need to feel cohesive, what's the best AI-generation workflow to maintain style consistency across a full asset set?
+
+4. **WebSocket vs SSE** — For a one-way data stream (server→display), Server-Sent Events might be simpler than WebSocket. Any strong reason to prefer one over the other?
+
+5. **Camera/animation system** — Any recommended patterns for a "living painting" that smoothly transitions between viewport presets while following real-time events?
+
+---
+
+## 11. PHASE 1 MINIMUM VIABLE FORGE
+
+To make Phase 1 concrete and achievable in a weekend:
+
+### What Gets Built
+
+1. **Static HTML page** with Canvas 2D (or PixiJS)
+2. **8 colored circles** at fixed positions representing servers
+3. **Labels** with server names
+4. **Connection lines** (simple straight lines for now)
+5. **Color-coded health** — green/yellow/red based on infrastructure module data
+6. **Auto-refresh** — poll `/admin/infrastructure/refresh` every 60 seconds
+7. **Basic particle** — one animated particle flowing from Cloudflare to Command Center on loop
+8. **Full-screen** — no UI chrome, black background, looks intentional on a wall
+
+### What Gets Deferred
+
+- Illustrated assets (circles only)
+- WebSocket real-time events (polling only)
+- Sound
+- Camera movement
+- Touch interaction
+- Game server villages
+- External territories (except Cloudflare)
+- Trinity figurines
+- Day/night cycle
+
+### Success: "Okay, this is already cool"
+
+If colored circles update health in real-time and one particle flows, that's the proof of concept. Everything else is iteration on a working foundation.
+
+---
+
+## Summary of Changes from Original Spec
+
+| Area | Original | Refined |
+|------|----------|---------|
+| Data sources | Listed conceptually | Mapped to specific existing API endpoints |
+| Event architecture | Implied | Explicit event bus design with format spec |
+| Asset creation | Not addressed | Three-option pipeline with phased recommendation |
+| Renderer | "Canvas 2D or WebGL" | PixiJS recommended with rationale |
+| Layout | Described geographically | Concrete coordinate system proposed |
+| Connections | "Energy streams" | Bezier curve routing with particle config |
+| Performance | Not mentioned | Budget table with hard limits |
+| Camera system | "Cycles viewing angles" | Named presets with durations and transitions |
+| Sound | "Optional" | Layered design with triggers |
+| Hosting | Three hardware options | Phased recommendation (no new hardware for Phase 1) |
+| Phase 1 scope | Listed features | Stripped to absolute minimum viable |
+| Gemini questions | Not included | 5 targeted architectural questions |
+
+---
+
+**This addendum complements the original spec. The Reconciler's vision is the soul. This is the skeleton.**
+
+💙🔥❄️
+
+Chronicler #80  
+April 11, 2026