feat: Codebase Genome — the-nexus full analysis (#672)

Complete GENOME.md for the-nexus repository:

- Project overview (3D world, Three.js, portal architecture)
- Architecture diagram (Mermaid)
- Entry points and data flow
- Key abstractions (NEXUS, SpatialMemory, Portal System, GOFAI)
- API surface (internal + external)
- Dependencies (Three.js, Python WebSocket)
- Test coverage gaps (7 critical paths untested)
- Security considerations (WebSocket auth, localStorage)
- Technical debt (4082-line app.js, no TypeScript)
- Migration notes from CLAUDE.md

Closes #672

the-nexus-GENOME.md

@@ -0,0 +1,319 @@
+# GENOME.md — the-nexus
+
+**Generated:** 2026-04-14  
+**Repo:** Timmy_Foundation/the-nexus  
+**Analysis:** Codebase Genome #672
+
+---
+
+## Project Overview
+
+The Nexus is Timmy's canonical 3D home-world — a browser-based Three.js application that serves as:
+1. **Local-first training ground** for Timmy (the sovereign AI)
+2. **Wizardly visualization surface** for the fleet system
+3. **Portal architecture** connecting to other worlds and services
+
+The app is a real-time 3D environment with spatial memory, GOFAI reasoning, agent presence, and portal-based navigation.
+
+---
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph Browser["BROWSER LAYER"]
+        HTML[index.html]
+        APP[app.js - 4082 lines]
+        CSS[style.css]
+        Worker[gofai_worker.js]
+    end
+    
+    subgraph ThreeJS["THREE.JS RENDERING"]
+        Scene[Scene Management]
+        Camera[Camera System]
+        Renderer[WebGL Renderer]
+        Post[Post-processing<br/>Bloom, SMAA]
+        Physics[Physics/Player]
+    end
+    
+    subgraph Nexus["NEXUS COMPONENTS"]
+        SM[SpatialMemory]
+        SA[SpatialAudio]
+        MB[MemoryBirth]
+        MO[MemoryOptimizer]
+        MI[MemoryInspect]
+        MP[MemoryPulse]
+        RT[ReasoningTrace]
+        RV[ResonanceVisualizer]
+    end
+    
+    subgraph GOFAI["GOFAI REASONING"]
+        Worker2[Web Worker]
+        Rules[Rule Engine]
+        Facts[Fact Store]
+        Inference[Inference Loop]
+    end
+    
+    subgraph Backend["BACKEND SERVICES"]
+        Server[server.py<br/>WebSocket Bridge]
+        L402[L402 Cost API]
+        Portal[Portal Registry]
+    end
+    
+    subgraph Data["DATA/PERSISTENCE"]
+        Local[localStorage]
+        IDB[IndexedDB]
+        JSON[portals.json]
+        Vision[vision.json]
+    end
+    
+    HTML --> APP
+    APP --> ThreeJS
+    APP --> Nexus
+    APP --> GOFAI
+    APP --> Backend
+    APP --> Data
+    
+    Worker2 --> APP
+    Server --> APP
+```
+
+---
+
+## Entry Points
+
+### Primary Entry
+- **`index.html`** — Main HTML shell, loads app.js
+- **`app.js`** — Main application (4082 lines), Three.js scene setup
+
+### Secondary Entry Points
+- **`boot.js`** — Bootstrap sequence
+- **`bootstrap.mjs`** — ES module bootstrap
+- **`server.py`** — WebSocket bridge server
+
+### Configuration Entry Points
+- **`portals.json`** — Portal definitions and destinations
+- **`vision.json`** — Vision/agent configuration
+- **`config/fleet_agents.json`** — Fleet agent definitions
+
+---
+
+## Data Flow
+
+```
+User Input
+    ↓
+app.js (Event Loop)
+    ↓
+┌─────────────────────────────────────┐
+│ Three.js Scene                      │
+│ - Player movement                   │
+│ - Camera controls                   │
+│ - Physics simulation                │
+│ - Portal detection                  │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ Nexus Components                    │
+│ - SpatialMemory (room/context)      │
+│ - MemoryBirth (new memories)        │
+│ - MemoryPulse (heartbeat)           │
+│ - ReasoningTrace (GOFAI output)     │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ GOFAI Worker (off-thread)           │
+│ - Rule evaluation                   │
+│ - Fact inference                    │
+│ - Decision making                   │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
+│ Backend Services                    │
+│ - WebSocket (server.py)             │
+│ - L402 cost API                     │
+│ - Portal registry                   │
+└─────────────────────────────────────┘
+    ↓
+Persistence (localStorage/IndexedDB)
+```
+
+---
+
+## Key Abstractions
+
+### 1. Nexus Object (`NEXUS`)
+Central configuration and state object containing:
+- Color palette
+- Room definitions
+- Portal configurations
+- Agent settings
+
+### 2. SpatialMemory
+Manages room-based context for the AI agent:
+- Room transitions trigger context switches
+- Facts are stored per-room
+- NPCs have location awareness
+
+### 3. Portal System
+Connects the 3D world to external services:
+- Portals defined in `portals.json`
+- Each portal links to a service/endpoint
+- Visual indicators in 3D space
+
+### 4. GOFAI Worker
+Off-thread reasoning engine:
+- Rule-based inference
+- Fact store with persistence
+- Decision making for agent behavior
+
+### 5. Memory Components
+- **MemoryBirth**: Creates new memories from interactions
+- **MemoryOptimizer**: Compresses and deduplicates memories
+- **MemoryPulse**: Heartbeat system for memory health
+- **MemoryInspect**: Debug/inspection interface
+
+---
+
+## API Surface
+
+### Internal APIs (JavaScript)
+
+| Module | Export | Purpose |
+|--------|--------|---------|
+| `app.js` | `NEXUS` | Main config/state object |
+| `SpatialMemory` | class | Room-based context management |
+| `SpatialAudio` | class | 3D positional audio |
+| `MemoryBirth` | class | Memory creation |
+| `MemoryOptimizer` | class | Memory compression |
+| `ReasoningTrace` | class | GOFAI reasoning visualization |
+
+### External APIs (HTTP/WebSocket)
+
+| Endpoint | Protocol | Purpose |
+|----------|----------|---------|
+| `ws://localhost:PORT` | WebSocket | Real-time bridge to backend |
+| `http://localhost:8080/api/cost-estimate` | HTTP | L402 cost estimation |
+| Portal endpoints | Various | External service connections |
+
+---
+
+## Dependencies
+
+### Runtime Dependencies
+- **Three.js** — 3D rendering engine
+- **Three.js Addons** — Post-processing (Bloom, SMAA)
+
+### Build Dependencies
+- **ES Modules** — Native browser modules
+- **No bundler** — Direct script loading
+
+### Backend Dependencies
+- **Python 3.x** — server.py
+- **WebSocket** — Real-time communication
+
+---
+
+## Test Coverage
+
+### Existing Tests
+- `tests/boot.test.js` — Bootstrap sequence tests
+
+### Test Gaps
+1. **Three.js scene initialization** — No tests
+2. **Portal system** — No tests
+3. **Memory components** — No tests
+4. **GOFAI worker** — No tests
+5. **WebSocket communication** — No tests
+6. **Spatial memory transitions** — No tests
+7. **Physics/player movement** — No tests
+
+### Recommended Test Priorities
+1. Portal detection and activation
+2. Spatial memory room transitions
+3. GOFAI worker message passing
+4. WebSocket connection handling
+5. Memory persistence (localStorage/IndexedDB)
+
+---
+
+## Security Considerations
+
+### Current Risks
+1. **WebSocket without auth** — server.py has no authentication
+2. **localStorage sensitive data** — Memories stored unencrypted
+3. **CORS open** — No origin restrictions on WebSocket
+4. **L402 endpoint** — Cost API may expose internal state
+
+### Mitigations
+1. Add WebSocket authentication
+2. Encrypt sensitive memories
+3. Restrict CORS origins
+4. Rate limit L402 endpoint
+
+---
+
+## File Structure
+
+```
+the-nexus/
+├── app.js                    # Main app (4082 lines)
+├── index.html                # HTML shell
+├── style.css                 # Styles
+├── server.py                 # WebSocket bridge
+├── boot.js                   # Bootstrap
+├── bootstrap.mjs             # ES module bootstrap
+├── gofai_worker.js           # GOFAI web worker
+├── portals.json              # Portal definitions
+├── vision.json               # Vision config
+├── nexus/                    # Nexus components
+│   └── components/
+│       ├── spatial-memory.js
+│       ├── spatial-audio.js
+│       ├── memory-birth.js
+│       ├── memory-optimizer.js
+│       ├── memory-inspect.js
+│       ├── memory-pulse.js
+│       ├── reasoning-trace.js
+│       └── resonance-visualizer.js
+├── config/                   # Configuration
+├── docs/                     # Documentation
+├── tests/                    # Tests
+├── agent/                    # Agent components
+├── bin/                      # Scripts
+└── assets/                   # Static assets
+```
+
+---
+
+## Technical Debt
+
+1. **Large app.js** (4082 lines) — Should be split into modules
+2. **No TypeScript** — Pure JavaScript, no type safety
+3. **Manual DOM manipulation** — Could use a framework
+4. **No build system** — Direct ES modules, no optimization
+5. **Limited error handling** — Minimal try/catch coverage
+
+---
+
+## Migration Notes
+
+From CLAUDE.md:
+- Current `main` does NOT ship the old root frontend files
+- A clean checkout serves a directory listing
+- The live browser shell exists in legacy form at `/Users/apayne/the-matrix`
+- Migration priorities: #684 (docs), #685 (legacy audit), #686 (smoke tests), #687 (restore shell)
+
+---
+
+## Next Steps
+
+1. **Restore browser shell** — Bring frontend back to main
+2. **Add tests** — Cover critical paths (portals, memory, GOFAI)
+3. **Split app.js** — Modularize the 4082-line file
+4. **Add authentication** — Secure WebSocket and APIs
+5. **TypeScript migration** — Add type safety
+
+---
+
+*Generated by Codebase Genome pipeline — Issue #672*