# joelmale/nexusvtt architecture

> Architecture diagram of the GitHub repository joelmale/nexusvtt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joelmale/nexusvtt
- Repository: https://github.com/joelmale/nexusvtt

## Overview

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: [`apps/codex/services/doc-api/src`](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-api/src) (Document API), [`apps/vtt`](https://github.com/joelmale/nexusvtt/tree/main/apps/vtt) (Tabletop session), [`apps/codex/services/doc-processor/src`](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-processor/src) (Processing worker), [`apps/forge`](https://github.com/joelmale/nexusvtt/tree/main/apps/forge) (Character builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vtt["Nexus VTT"]
  node_vtt_app["Tabletop session"]
  node_vtt_camera["Camera gestures"]
  node_vtt_scene_store["Scene storage bridge"]
  node_vtt_indexeddb[("IndexedDB worker<br/>[storageWorker.ts]")]
  node_vtt_backend["VTT backend proxy"]
end

subgraph group_forge["NexusForge"]
  node_forge_app["Character builder"]
  node_forge_sheet["Character sheets<br/>[CharacterSheet.tsx]"]
  node_forge_export["Character export"]
end

subgraph group_codex["NexusCodex"]
  node_codex_ui["DM document UI"]
  node_admin_ui["Admin dashboard"]
end

subgraph group_codex_runtime["Codex Runtime"]
  node_doc_api["Document API"]
  node_doc_processor["Processing worker"]
  node_ocr["OCR and layout"]
  node_extract["Entity extraction"]
  node_layout_engine["Page layout engine<br/>[layout_engine.py]"]
  node_doc_storage[("Document storage<br/>[s3.service.ts]")]
  node_doc_search["Document search"]
  node_realtime["Live collaboration"]
end

node_players(("Players and GMs"))
node_ollama["Ollama model service"]

node_players -->|"run sessions"| node_vtt_app
node_vtt_app -->|"handle gestures"| node_vtt_camera
node_vtt_app -->|"manage scenes"| node_vtt_scene_store
node_vtt_scene_store -->|"persist entities"| node_vtt_indexeddb
node_players -->|"build characters"| node_forge_app
node_forge_app -->|"edit character"| node_forge_sheet
node_forge_app -->|"export character"| node_forge_export
node_forge_export -.->|"import character"| node_vtt_app
node_players -->|"manage campaign material"| node_codex_ui
node_players -->|"administer documents"| node_admin_ui
node_codex_ui -->|"request document actions"| node_doc_api
node_admin_ui -->|"request admin actions"| node_doc_api
node_doc_api -->|"dispatch processing"| node_doc_processor
node_doc_processor -->|"request OCR"| node_ocr
node_doc_processor -->|"request layout"| node_layout_engine
node_doc_processor -->|"extract entities"| node_extract
node_extract -.->|"request extraction"| node_ollama
node_extract -->|"cache responses"| node_doc_storage
node_doc_api -->|"read and write files"| node_doc_storage
node_doc_api -->|"search documents"| node_doc_search
node_players -->|"collaborate live"| node_realtime
node_vtt_app -.->|"request documents"| node_vtt_backend
node_vtt_backend -.->|"proxy requests"| node_doc_api

click node_vtt_app "https://github.com/joelmale/nexusvtt/tree/main/apps/vtt"
click node_vtt_camera "https://github.com/joelmale/nexusvtt/blob/main/apps/vtt/src/utils/cameraGestureEngine.ts"
click node_vtt_scene_store "https://github.com/joelmale/nexusvtt/blob/main/apps/vtt/src/services/linearFlowStorage.ts"
click node_vtt_indexeddb "https://github.com/joelmale/nexusvtt/blob/main/apps/vtt/src/workers/storageWorker.ts"
click node_forge_app "https://github.com/joelmale/nexusvtt/tree/main/apps/forge"
click node_forge_sheet "https://github.com/joelmale/nexusvtt/blob/main/apps/forge/src/components/CharacterSheet/CharacterSheet.tsx"
click node_forge_export "https://github.com/joelmale/nexusvtt/tree/main/apps/forge"
click node_codex_ui "https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/dm-ui/src"
click node_admin_ui "https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/admin-ui/src"
click node_doc_api "https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-api/src"
click node_doc_processor "https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-processor/src"
click node_ocr "https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/ocr-service/src"
click node_extract "https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/doc-processor/src/services/llm-extraction.service.ts"
click node_layout_engine "https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/ocr-service/src/layout_engine.py"
click node_doc_storage "https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/doc-api/src/services/s3.service.ts"
click node_doc_search "https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/doc-api/src/services/chunk-search.service.ts"
click node_realtime "https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-websocket/src"
click node_vtt_backend "https://github.com/joelmale/nexusvtt/tree/main/apps/vtt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vtt_app,node_vtt_camera,node_vtt_scene_store,node_vtt_indexeddb,node_vtt_backend toneBlue
class node_forge_app,node_forge_sheet,node_forge_export toneAmber
class node_codex_ui,node_admin_ui toneMint
class node_doc_api,node_doc_processor,node_ocr,node_extract,node_layout_engine,node_doc_storage,node_doc_search,node_realtime toneRose
class node_players,node_ollama toneIndigo
```

## Components

### Nexus VTT

- [Tabletop session](https://github.com/joelmale/nexusvtt/tree/main/apps/vtt): `apps/vtt`
- [Camera gestures](https://github.com/joelmale/nexusvtt/blob/main/apps/vtt/src/utils/cameraGestureEngine.ts): `apps/vtt/src/utils/cameraGestureEngine.ts`
- [Scene storage bridge](https://github.com/joelmale/nexusvtt/blob/main/apps/vtt/src/services/linearFlowStorage.ts): `apps/vtt/src/services/linearFlowStorage.ts`
- [IndexedDB worker](https://github.com/joelmale/nexusvtt/blob/main/apps/vtt/src/workers/storageWorker.ts): `apps/vtt/src/workers/storageWorker.ts`
- [VTT backend proxy](https://github.com/joelmale/nexusvtt/tree/main/apps/vtt): `apps/vtt`

### NexusForge

- [Character builder](https://github.com/joelmale/nexusvtt/tree/main/apps/forge): `apps/forge`
- [Character sheets](https://github.com/joelmale/nexusvtt/blob/main/apps/forge/src/components/CharacterSheet/CharacterSheet.tsx): `apps/forge/src/components/CharacterSheet/CharacterSheet.tsx`
- [Character export](https://github.com/joelmale/nexusvtt/tree/main/apps/forge): `apps/forge`

### NexusCodex

- [DM document UI](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/dm-ui/src): `apps/codex/services/dm-ui/src`
- [Admin dashboard](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/admin-ui/src): `apps/codex/services/admin-ui/src`

### Codex Runtime

- [Document API](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-api/src): `apps/codex/services/doc-api/src`
- [Processing worker](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-processor/src): `apps/codex/services/doc-processor/src`
- [OCR and layout](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/ocr-service/src): `apps/codex/services/ocr-service/src`
- [Entity extraction](https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/doc-processor/src/services/llm-extraction.service.ts): `apps/codex/services/doc-processor/src/services/llm-extraction.service.ts`
- [Page layout engine](https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/ocr-service/src/layout_engine.py): `apps/codex/services/ocr-service/src/layout_engine.py`
- [Document storage](https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/doc-api/src/services/s3.service.ts): `apps/codex/services/doc-api/src/services/s3.service.ts`
- [Document search](https://github.com/joelmale/nexusvtt/blob/main/apps/codex/services/doc-api/src/services/chunk-search.service.ts): `apps/codex/services/doc-api/src/services/chunk-search.service.ts`
- [Live collaboration](https://github.com/joelmale/nexusvtt/tree/main/apps/codex/services/doc-websocket/src): `apps/codex/services/doc-websocket/src`

### Other components

- **Players and GMs**
- **Ollama model service**

## Connections

- 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