Timmy Time
4582653bb4
Some checks failed
Smoke Test / smoke (pull_request) Failing after 16s
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
320 lines
9.4 KiB
Markdown
320 lines
9.4 KiB
Markdown
# 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*
|