timmy-home/the-nexus-GENOME.md

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

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