How joelmale/nexusvtt works
Nexus is a suite of browser-based tabletop RPG tools, with the VTT as its primary app and Forge and Codex as standalone apps that also integrate with it. The main user workflows are running multiplayer tabletop sessions, creating and managing characters, and ingesting/searching campaign documents with live collaboration. The graph preserves those product areas and Codex’s documented processing stages. Sampled source is limited, so some subsystem links rely on README documentation; contract-package paths are omitted because they are absent from the supplied tree.
Main entry points: doc-api/src Document API · vtt Tabletop session · doc-processor/src Processing worker · forge Character builder
Components 20
Nexus VTT
- Tabletop session
apps/vtt - Camera gestures
apps/vtt/src/utils/cameraGestureEngine.ts - Scene storage bridge
apps/vtt/src/services/linearFlowStorage.ts - IndexedDB worker
apps/vtt/src/workers/storageWorker.ts - VTT backend proxy
apps/vtt
NexusForge
- Character builder
apps/forge - Character sheets
apps/forge/src/components/CharacterSheet/CharacterSheet.tsx - Character export
apps/forge
NexusCodex
- DM document UI
apps/codex/services/dm-ui/src - Admin dashboard
apps/codex/services/admin-ui/src
Codex Runtime
- Document API
apps/codex/services/doc-api/src - Processing worker
apps/codex/services/doc-processor/src - OCR and layout
apps/codex/services/ocr-service/src - Entity extraction
apps/codex/services/doc-processor/src/services/llm-extraction.service.ts - Page layout engine
apps/codex/services/ocr-service/src/layout_engine.py - Document storage
apps/codex/services/doc-api/src/services/s3.service.ts - Document search
apps/codex/services/doc-api/src/services/chunk-search.service.ts - Live collaboration
apps/codex/services/doc-websocket/src
Other components
- Players and GMs
- Ollama model service
Connections 23
- Players and GMs → Tabletop session: run sessions
- Tabletop session → Camera gestures: handle gestures
- Tabletop session → Scene storage bridge: manage scenes
- Scene storage bridge → IndexedDB worker: persist entities
- Players and GMs → Character builder: build characters
- Character builder → Character sheets: edit character
- Character builder → Character export: export character
- Character export → Tabletop session: import character
- Players and GMs → DM document UI: manage campaign material
- Players and GMs → Admin dashboard: administer documents
- DM document UI → Document API: request document actions
- Admin dashboard → Document API: request admin actions
- Document API → Processing worker: dispatch processing
- Processing worker → OCR and layout: request OCR
- Processing worker → Page layout engine: request layout
- Processing worker → Entity extraction: extract entities
- Entity extraction → Ollama model service: request extraction
- Entity extraction → Document storage: cache responses
- Document API → Document storage: read and write files
- Document API → Document search: search documents
- Players and GMs → Live collaboration: collaborate live
- Tabletop session → VTT backend proxy: request documents
- VTT backend proxy → Document API: proxy requests