How johnrobins204/vox-magistri-be works
This repository implements a browser-based AI-assisted tabletop role-playing game with a FastAPI backend. The user workflow centers on choosing a character and session, sending a message or command, and receiving a generated narrative; supporting branches manage reference catalogs, tool commands, and campaign-world entities. The backend assembles services, processes inference asynchronously, and exposes session, world, reference, and intelligence routes. The README is empty, and some source was not sampled, so uncertain connections—especially browser-to-server transport details—are omitted.
Main entry points: inference_service.py Inference Worker · App.tsx Game UI · factory.py App Factory · build_services.py Service Builder
Components 23
Browser App
- Game UI
frontend/src/App.tsx - Character Editor
frontend/src/components/CharacterCreator.tsx - Narrative Log
frontend/src/components/NarrativeLog.tsx - API Client
frontend/src/lib/api.ts - Socket Client
frontend/src/lib/ws.ts
API Surface
- App Factory
app/factory.py - Session Routes
app/api/v1/session.py - Intelligence Routes
app/api/v1/intelligence.py - World Routes
app/api/v1/world.py - WebSocket Routes
app/api/v1/ws.py
Game Runtime
- Service Builder
app/services/build_services.py - Inference Worker
app/services/inference_service.py - LLM Client
app/intelligence/client.py - Tool Dispatcher
app/services/tool_service.py - Command Handler
app/intelligence/tool_handler.py - Game Commands
app/intelligence/tools
Game Knowledge
- Reference Catalog
app/reference - Prompt Builders
app/intelligence/prompt_builders.py
Campaign State
- Session Store
app/services/repos.py - World Mining
app/services/world_mining.py - World Store
app/services/repos.py
Other components
- Player
- Ollama
Connections 26
- Player → Game UI: uses
- Game UI → Character Editor: opens
frontend/src/App.tsx - Game UI → API Client: loads and updates
frontend/src/App.tsx - Game UI → Socket Client: uses
frontend/src/App.tsx - Game UI → Narrative Log: renders
frontend/src/App.tsx - App Factory → Session Routes: registers
app/factory.py - App Factory → Intelligence Routes: registers
app/factory.py - App Factory → World Routes: registers
app/factory.py - App Factory → WebSocket Routes: registers
app/factory.py - Service Builder → Inference Worker: constructs
app/services/build_services.py - Service Builder → Tool Dispatcher: constructs
app/services/build_services.py - Service Builder → Reference Catalog: loads
app/services/build_services.py - Service Builder → World Mining: uses stoplist
app/services/build_services.py - Session Routes → Session Store: reads and writes
app/api/v1/session.py - Session Routes → Inference Worker: enqueues
app/api/v1/session.py - Intelligence Routes → Tool Dispatcher: invokes
app/api/v1/intelligence.py - World Routes → World Store: accesses
app/api/v1/world.py - Inference Worker → LLM Client: requests generation
app/services/inference_service.py - Inference Worker → Prompt Builders: builds prompts
app/services/inference_service.py - Inference Worker → Session Store: reads and writes
app/services/inference_service.py - Inference Worker → Command Handler: dispatches commands
app/services/inference_service.py - Inference Worker → World Mining: mines replies
app/services/inference_service.py - Command Handler → Game Commands: discovers and runs
app/intelligence/tool_handler.py - Tool Dispatcher → Game Commands: discovers tools
app/services/tool_service.py - World Mining → World Store: records entities
app/services/world_mining.py - LLM Client → Ollama: sends chat
app/intelligence/client.py