[GOVERNING] App.js Modularization — ES Module Architecture #409

New Issue

perplexity · 2026-03-24T17:07:31Z

perplexity commented

2026-03-24 17:07:31 +00:00

[GOVERNING] App.js Modularization — ES Module Architecture

Alexander's Directive

"5000 lines in one file? Sounds like it's time to break it up. This is JavaScript no need for a mono file, highly inefficient for source control and multi agent work. App.js should almost never change. Kapishe"

Goal

Break the 5164-line monolithic app.js into a clean ES module architecture where:

app.js is a thin orchestrator (~200 lines) that almost never changes
Each visual system is an independent module
Multiple agents can work on different modules simultaneously without merge conflicts
A single Global Animation Ticker drives all updates

Target Architecture

the-nexus/
├── app.js                    # THIN ORCHESTRATOR (~200 lines)
├── modules/
│   ├── core/
│   │   ├── scene.js          # THREE.Scene, camera, renderer, controls
│   │   ├── ticker.js         # Global Animation Clock (single RAF)
│   │   ├── theme.js          # NEXUS.theme — all colors, fonts, weights
│   │   ├── audio.js          # Web Audio engine
│   │   └── state.js          # Shared data bus (activity, weather, BTC, agents)
│   ├── terrain/
│   │   ├── island.js         # Floating island + crystals
│   │   ├── clouds.js         # Cloud layer (weather-tethered)
│   │   └── stars.js          # Star field + constellations (BTC-tethered)
│   ├── effects/
│   │   ├── matrix-rain.js    # Matrix rain (commit-tethered)
│   │   ├── lightning.js      # Lightning arcs
│   │   ├── energy-beam.js    # Energy beam (agent-count-tethered)
│   │   ├── rune-ring.js      # Rune ring (portal-tethered)
│   │   ├── gravity-zones.js  # Gravity anomaly zones
│   │   └── shockwave.js      # Shockwave, fireworks, merge flash
│   ├── panels/
│   │   ├── heatmap.js        # Commit heatmap + zones
│   │   ├── agent-board.js    # Agent status (Gitea API)
│   │   ├── dual-brain.js     # Dual-brain panel
│   │   ├── lora-panel.js     # LoRA adapter panel
│   │   ├── sovereignty.js    # Sovereignty meter
│   │   └── earth.js          # Holographic earth
│   ├── portals/
│   │   ├── portal-system.js  # Portal creation, warp, health checks
│   │   └── commit-banners.js # Floating commit banners
│   ├── narrative/
│   │   ├── bookshelves.js    # Floating bookshelves (SOUL.md)
│   │   ├── oath.js           # Oath display
│   │   └── chat.js           # Chat panel, speech bubbles
│   ├── data/
│   │   ├── gitea.js          # All Gitea API calls
│   │   ├── weather.js        # Open-Meteo fetch
│   │   ├── bitcoin.js        # BTC block height
│   │   └── loaders.js        # JSON file loaders
│   └── utils/
│       ├── perlin.js         # Perlin noise
│       ├── geometry.js       # Geometry helpers
│       └── canvas-utils.js   # Canvas texture helpers

Module Contract

Every module must export:

// Required
export function init(scene, state, theme) { ... }

// Required — called by ticker every frame
export function update(elapsed, delta) { ... }

// Optional — cleanup
export function dispose() { ... }

The ticker calls update() on every subscribed module once per frame. No module may call requestAnimationFrame directly.

Migration Phases

Phase 1: Core Foundation

Extract core/scene.js (camera, renderer, controls, resize)
Extract core/ticker.js (single RAF loop, subscribe/unsubscribe API)
Extract core/theme.js (NEXUS.colors → NEXUS.theme with fonts, weights, glows)
Extract core/state.js (shared reactive data bus)
app.js imports core, wires up, still contains everything else temporarily

Phase 2: Data Layer

Extract data/gitea.js (all Gitea API fetches)
Extract data/weather.js (Open-Meteo fetch)
Extract data/bitcoin.js (blockstream fetch)
Extract data/loaders.js (JSON file loading)
No visual changes — pure data extraction

Phase 3: Panels

Extract each panel to its own module
Each panel reads from state.js, renders to canvas textures
Test each panel independently

Phase 4: Effects

Extract matrix rain, lightning, energy beam, rune ring, gravity zones
Each effect subscribes to ticker, reads from state

Phase 5: Terrain, Portals, Narrative

Extract remaining systems
app.js becomes pure orchestrator
Final cleanup

Rules

Each phase is its own PR (micro-commits within)
node --check app.js must pass after every commit
No new draw calls — existing meshes only move to modules
Data Integrity Standard from CLAUDE.md applies to every PR
After Phase 5, app.js should be ~200 lines of imports + init() calls

Cross-References

Sovereignty Manifest: hermes-agent #115
Honesty Pass: the-nexus PR #408 (merged)
Data Integrity Standard: CLAUDE.md

Dependencies

Phase 1 (core/) must complete before any other phase
Phases 2-5 can partially overlap but should maintain order for stability

# [GOVERNING] App.js Modularization — ES Module Architecture ## Alexander's Directive > "5000 lines in one file? Sounds like it's time to break it up. This is JavaScript no need for a mono file, highly inefficient for source control and multi agent work. App.js should almost never change. Kapishe" ## Goal Break the 5164-line monolithic `app.js` into a clean ES module architecture where: 1. `app.js` is a thin orchestrator (~200 lines) that almost never changes 2. Each visual system is an independent module 3. Multiple agents can work on different modules simultaneously without merge conflicts 4. A single Global Animation Ticker drives all updates ## Target Architecture ``` the-nexus/ ├── app.js # THIN ORCHESTRATOR (~200 lines) ├── modules/ │ ├── core/ │ │ ├── scene.js # THREE.Scene, camera, renderer, controls │ │ ├── ticker.js # Global Animation Clock (single RAF) │ │ ├── theme.js # NEXUS.theme — all colors, fonts, weights │ │ ├── audio.js # Web Audio engine │ │ └── state.js # Shared data bus (activity, weather, BTC, agents) │ ├── terrain/ │ │ ├── island.js # Floating island + crystals │ │ ├── clouds.js # Cloud layer (weather-tethered) │ │ └── stars.js # Star field + constellations (BTC-tethered) │ ├── effects/ │ │ ├── matrix-rain.js # Matrix rain (commit-tethered) │ │ ├── lightning.js # Lightning arcs │ │ ├── energy-beam.js # Energy beam (agent-count-tethered) │ │ ├── rune-ring.js # Rune ring (portal-tethered) │ │ ├── gravity-zones.js # Gravity anomaly zones │ │ └── shockwave.js # Shockwave, fireworks, merge flash │ ├── panels/ │ │ ├── heatmap.js # Commit heatmap + zones │ │ ├── agent-board.js # Agent status (Gitea API) │ │ ├── dual-brain.js # Dual-brain panel │ │ ├── lora-panel.js # LoRA adapter panel │ │ ├── sovereignty.js # Sovereignty meter │ │ └── earth.js # Holographic earth │ ├── portals/ │ │ ├── portal-system.js # Portal creation, warp, health checks │ │ └── commit-banners.js # Floating commit banners │ ├── narrative/ │ │ ├── bookshelves.js # Floating bookshelves (SOUL.md) │ │ ├── oath.js # Oath display │ │ └── chat.js # Chat panel, speech bubbles │ ├── data/ │ │ ├── gitea.js # All Gitea API calls │ │ ├── weather.js # Open-Meteo fetch │ │ ├── bitcoin.js # BTC block height │ │ └── loaders.js # JSON file loaders │ └── utils/ │ ├── perlin.js # Perlin noise │ ├── geometry.js # Geometry helpers │ └── canvas-utils.js # Canvas texture helpers ``` ## Module Contract Every module must export: ```javascript // Required export function init(scene, state, theme) { ... } // Required — called by ticker every frame export function update(elapsed, delta) { ... } // Optional — cleanup export function dispose() { ... } ``` The ticker calls `update()` on every subscribed module once per frame. No module may call `requestAnimationFrame` directly. ## Migration Phases ### Phase 1: Core Foundation - Extract `core/scene.js` (camera, renderer, controls, resize) - Extract `core/ticker.js` (single RAF loop, subscribe/unsubscribe API) - Extract `core/theme.js` (NEXUS.colors → NEXUS.theme with fonts, weights, glows) - Extract `core/state.js` (shared reactive data bus) - `app.js` imports core, wires up, still contains everything else temporarily ### Phase 2: Data Layer - Extract `data/gitea.js` (all Gitea API fetches) - Extract `data/weather.js` (Open-Meteo fetch) - Extract `data/bitcoin.js` (blockstream fetch) - Extract `data/loaders.js` (JSON file loading) - No visual changes — pure data extraction ### Phase 3: Panels - Extract each panel to its own module - Each panel reads from `state.js`, renders to canvas textures - Test each panel independently ### Phase 4: Effects - Extract matrix rain, lightning, energy beam, rune ring, gravity zones - Each effect subscribes to ticker, reads from state ### Phase 5: Terrain, Portals, Narrative - Extract remaining systems - `app.js` becomes pure orchestrator - Final cleanup ## Rules - Each phase is its own PR (micro-commits within) - `node --check app.js` must pass after every commit - No new draw calls — existing meshes only move to modules - Data Integrity Standard from CLAUDE.md applies to every PR - After Phase 5, app.js should be ~200 lines of imports + init() calls ## Cross-References - Sovereignty Manifest: hermes-agent #115 - Honesty Pass: the-nexus PR #408 (merged) - Data Integrity Standard: CLAUDE.md ## Dependencies - Phase 1 (core/) must complete before any other phase - Phases 2-5 can partially overlap but should maintain order for stability

perplexity added the modularization p0-critical 222-epic labels 2026-03-24 17:07:31 +00:00

[GOVERNING] App.js Modularization — ES Module Architecture #409