Add SOUL Lattice v4 monitoring dashboard with Go backend

[Igor Holt (igor-holt)]

Summary

This PR introduces a complete full-stack monitoring system called "SOUL Lattice v4" — a real-time thermodynamic state dashboard with a Go backend simulator, React frontend cockpit, Cloudflare Workers security layer, and Cloud Run deployment infrastructure.

Key Changes

Backend (Go)

• backend/main.go: Entry point that initializes the server and simulator, handles graceful shutdown
• backend/server.go: HTTP server with chi router, SSE streaming endpoint (/events), state management endpoints, and CORS support
• backend/simulator.go: Stochastic simulator that drifts system metrics (coherence, breath, thermodynamic yield, GPU utilization, token generation) with realistic constraints and state transitions
• backend/state.go: Core state struct with validation, pretty-printing, and uptime formatting utilities
• backend/Containerfile: Multi-stage Alpine-based container build for Cloud Run deployment
• backend/go.mod: Go module dependencies (chi router, CORS middleware)

Frontend (React + TypeScript)

• frontend/src/App.tsx: Main React component (SoulCockpit) that:
  • Connects to backend via EventSource for real-time SSE updates
  • Displays 6 metric cards (coherence, breath, yield, token velocity, surplus tokens, GPU utilization)
  • Renders a live coherence timeline chart using Recharts
  • Shows connection status indicator and system state metadata
  • Implements cyberpunk-themed UI with neon green (#00ff9f) on dark background
• frontend/src/index.tsx: React entry point
• frontend/package.json: Dependencies (React 18, Recharts, react-scripts)
• frontend/tsconfig.json: TypeScript configuration
• frontend/public/index.html: HTML shell with dark theme meta tags

Cloudflare Workers Security Layer

• workers/index.js (modified): Complete rewrite adding:
  • JWT validation against Cloudflare Access JWKS endpoint
  • Static asset serving (JS, CSS, images) without auth for SPA bootstrap
  • Health check endpoint for uptime monitoring
  • API proxy to Go backend with header forwarding (user email, IP, etc.)
  • SPA fallback routing (all non-API routes → index.html for React Router)
  • Comprehensive error handling and logging

Deployment & Configuration

• wrangler.toml (modified): Updated with:
  • Assets binding for React SPA build output
  • Production environment (yennefer.quest) with Cloud Run backend URL
  • Staging environment (staging.yennefer.quest) with localhost backend
  • Node.js compatibility flags
• firebase.json: Firebase Hosting config with:
  • Rewrites for /api/** to Cloud Run service
  • SPA fallback to index.html
  • Cache headers (no-cache for API, long-lived for JS assets)
• deploy-podman.sh: Bash deployment script orchestrating:
  • Podman container build and GCR push
  • Cloud Run deployment with resource constraints
  • Firebase Hosting deployment
  • Post-deployment verification

Root Configuration

• package.json (modified): Added Wrangler CLI scripts for worker deployment

Notable Implementation Details

1. Real-time Streaming: Backend uses Server-Sent Events (SSE) to push state updates every 800ms to all connected clients
2. Stochastic Simulation: Metrics drift within realistic bounds using random walk with clamping; coherence state transitions between "Stable", "Hyperstable", and "Fracturing" based on thresholds
3. Security: Cloudflare Access JWT validation gates all non-static routes; static assets bypass auth to allow SPA bootstrap
4. Responsive UI: CSS Grid layout adapts metric cards; Recharts handles timeline visualization with custom tooltip styling
5. Multi-environment: Separate staging (localhost) and production (Cloud Run) configurations in Wrangler
6. Graceful Shutdown: Go server handles SIG

https://claude.ai/code/session_013cFiQZ1hnb4JrBj9DvDgip