diff --git a/docs/tasks/task-127-the-forge-living-art/REFINEMENT-ADDENDUM.md b/docs/tasks/task-127-the-forge-living-art/REFINEMENT-ADDENDUM.md new file mode 100644 index 0000000..cf0c5d2 --- /dev/null +++ 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