the-nexus/GENOME.md

GENOME.md — The Nexus Codebase Architecture Map

Generated: 2026-04-20 Repository: Timmy_Foundation/the-nexus Purpose: Comprehensive map of the Nexus codebase for developers and AI agents.

---

Overview

The Nexus is Timmy's canonical 3D/world repository — a sovereign AI agent visualization surface and local-first training ground. It combines a Three.js 3D browser world with Python cognition components, WebSocket bridges, and fleet orchestration tools.

Key Stats:

• ~357 source files
• 201 Python files
• 23 JavaScript files
• 107 Markdown docs
• 24 Shell scripts

---

Architecture

the-nexus/
├── app.js                    # Main Three.js 3D world (frontend entry)
├── index.html                # HTML shell
├── style.css                 # Global styles
├── server.py                 # WebSocket gateway
├── gofai_worker.js           # GOFAI web worker
├── portals.json              # Portal registry
├── vision.json               # Vision points config
├── provenance.json           # File integrity hashes
│
├── nexus/                    # Python cognition layer
│   ├── components/           # Frontend JS modules
│   ├── mnemosyne/            # Memory system
│   ├── mempalace/            # Long-term memory
│   └── symbolic-engine.js    # GOFAI rules
│
├── scripts/                  # Operational scripts
├── bin/                      # CLI tools
├── tests/                    # Test suite
├── docs/                     # Documentation
└── config/                   # Configuration files

---

Frontend (Browser World)

Entry Points

File	Purpose
index.html	HTML shell, HUD layout
app.js	Main Three.js app (~141K lines)
style.css	All styles (~61K)
gofai_worker.js	Off-thread GOFAI reasoning

Core Systems

System	File	Description
3D World	app.js	Three.js scene, camera, rendering
GOFAI	app.js	Symbolic rules, blackboard, planner
Memory	nexus/components/spatial-memory.js	3D memory crystals
Audio	nexus/components/spatial-audio.js	Spatial sound system
Portals	portals.json	External service links
Chat	app.js	Chat panel and messaging
HUD	app.js + style.css	Heads-up display

Components (nexus/components/)

Component	Purpose
spatial-memory.js	3D memory crystal visualization
spatial-audio.js	Spatial sound for memories
memory-birth.js	Memory creation animation
memory-pulse.js	BFS pulse wave on click
memory-inspect.js	Memory detail panel
memory-connections.js	Connection graph
memory-particles.js	Particle effects
memory-optimizer.js	Memory cleanup
session-rooms.js	Evennia room snapshots
timeline-scrubber.js	Time navigation
resonance-visualizer.js	Pattern visualization
portal-health-check.js	Portal status monitoring
spatial-chat.js	3D audio chat notifications

---

Backend (Python)

Core Services

File	Purpose
server.py	WebSocket gateway for real-time comms
multi_user_bridge.py	Multi-user MUD bridge
gitea_api/	Gitea API helpers

Scripts (scripts/)

Script	Purpose
cleanup-duplicate-prs.sh	Close duplicate PRs
check-existing-prs.sh	Pre-flight PR check
pr_backlog_analyzer.py	PR backlog analysis
audit_mempalace_privacy.py	Privacy audit
provision-runner.sh	Runner setup
runner_health_probe.sh	Health monitoring

Bin Tools (bin/)

Tool	Purpose
enforce_branch_protection.py	Branch protection enforcement
check_duplicate_milestones.py	Milestone cleanup
generate_provenance.py	Provenance hash generation

---

Data Files

File	Format	Purpose
portals.json	JSON	Portal registry (8 portals)
vision.json	JSON	Vision points
world_state.json	JSON	World state snapshot
provenance.json	JSON	File integrity hashes
manifest.json	JSON	PWA manifest

---

Configuration

File	Purpose
.gitea/branch-protection/	Branch protection rules
.github/workflows/	CI/CD workflows
config/	Runtime configuration
pytest.ini	Test configuration

---

Testing

Directory	Coverage
tests/	Unit and integration tests
tests/test_provenance.py	File integrity tests
tests/test_spatial_search.js	Spatial search tests

Run tests:

python3 -m pytest tests/ -v
node --test tests/*.js

---

Key Patterns

Component Pattern

const ComponentName = (() => {
  let _state = null;
  
  function init(config) { ... }
  function update(delta) { ... }
  
  return { init, update };
})();

export { ComponentName };

WebSocket Pattern

async def handler(websocket):
    async for message in websocket:
        # Process and broadcast
        pass

Portal Schema

{
  "id": "portal-id",
  "name": "Display Name",
  "portal_type": "game-world",
  "destination": { "url": "...", "type": "harness" }
}

---

Security

• WebSocket gateway binds to 127.0.0.1 by default
• Optional token authentication via NEXUS_WS_TOKEN
• Rate limiting on connections and messages
• Branch protection on main
• Provenance hash verification

See SECURITY.md for full details.

---

Related Repos

Repo	Relationship
timmy-config	Configuration and fleet management
hermes-agent	Agent runtime
timmy-home	SOUL.md and core docs
the-door	Crisis detection system

---

Quick Start

# Clone
git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus.git

# Run WebSocket gateway
python3 server.py

# Open browser world
open index.html

# Run tests
python3 -m pytest tests/

---

This GENOME.md is auto-maintained. Update when adding major new systems.