# johnrobins204/vox-magistri-be architecture

> Architecture diagram of the GitHub repository johnrobins204/vox-magistri-be, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnrobins204/vox-magistri-be
- Repository: https://github.com/johnrobins204/vox-magistri-be

## Overview

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: [`app/services/inference_service.py`](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/inference_service.py) (Inference Worker), [`frontend/src/App.tsx`](https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/App.tsx) (Game UI), [`app/factory.py`](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/factory.py) (App Factory), [`app/services/build_services.py`](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/build_services.py) (Service Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser App"]
  node_app_ui["Game UI<br/>[App.tsx]"]
  node_character_editor["Character Editor"]
  node_narrative_view["Narrative Log<br/>[NarrativeLog.tsx]"]
  node_browser_api["API Client<br/>[api.ts]"]
  node_browser_ws["Socket Client<br/>[ws.ts]"]
end

subgraph group_api["API Surface"]
  node_app_factory["App Factory<br/>[factory.py]"]
  node_session_routes["Session Routes<br/>[session.py]"]
  node_intelligence_routes["Intelligence Routes<br/>[intelligence.py]"]
  node_world_routes["World Routes<br/>[world.py]"]
  node_ws_routes["WebSocket Routes<br/>[ws.py]"]
end

subgraph group_runtime["Game Runtime"]
  node_service_builder["Service Builder<br/>[build_services.py]"]
  node_inference["Inference Worker"]
  node_llm_client["LLM Client<br/>[client.py]"]
  node_tool_service["Tool Dispatcher<br/>[tool_service.py]"]
  node_tool_handler["Command Handler<br/>[tool_handler.py]"]
  node_tool_modules["Game Commands"]
end

subgraph group_knowledge["Game Knowledge"]
  node_reference_catalog["Reference Catalog"]
  node_prompt_builders["Prompt Builders<br/>[prompt_builders.py]"]
end

subgraph group_state["Campaign State"]
  node_session_store[("Session Store<br/>[repos.py]")]
  node_world_mining["World Mining<br/>[world_mining.py]"]
  node_world_store[("World Store<br/>[repos.py]")]
end

node_player(("Player"))
node_ollama["Ollama"]

node_player -->|"uses"| node_app_ui
node_app_ui -->|"opens"| node_character_editor
node_app_ui -->|"loads and updates"| node_browser_api
node_app_ui -->|"uses"| node_browser_ws
node_app_ui -->|"renders"| node_narrative_view
node_app_factory -->|"registers"| node_session_routes
node_app_factory -->|"registers"| node_intelligence_routes
node_app_factory -->|"registers"| node_world_routes
node_app_factory -->|"registers"| node_ws_routes
node_service_builder -->|"constructs"| node_inference
node_service_builder -->|"constructs"| node_tool_service
node_service_builder -->|"loads"| node_reference_catalog
node_service_builder -->|"uses stoplist"| node_world_mining
node_session_routes -->|"reads and writes"| node_session_store
node_session_routes -->|"enqueues"| node_inference
node_intelligence_routes -->|"invokes"| node_tool_service
node_world_routes -.->|"accesses"| node_world_store
node_inference -->|"requests generation"| node_llm_client
node_inference -->|"builds prompts"| node_prompt_builders
node_inference -->|"reads and writes"| node_session_store
node_inference -.->|"dispatches commands"| node_tool_handler
node_inference -->|"mines replies"| node_world_mining
node_tool_handler -->|"discovers and runs"| node_tool_modules
node_tool_service -->|"discovers tools"| node_tool_modules
node_world_mining -->|"records entities"| node_world_store
node_llm_client -->|"sends chat"| node_ollama

click node_app_ui "https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/App.tsx"
click node_character_editor "https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/components/CharacterCreator.tsx"
click node_narrative_view "https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/components/NarrativeLog.tsx"
click node_browser_api "https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/lib/api.ts"
click node_browser_ws "https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/lib/ws.ts"
click node_app_factory "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/factory.py"
click node_session_routes "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/session.py"
click node_intelligence_routes "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/intelligence.py"
click node_world_routes "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/world.py"
click node_ws_routes "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/ws.py"
click node_service_builder "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/build_services.py"
click node_inference "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/inference_service.py"
click node_llm_client "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/intelligence/client.py"
click node_tool_service "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/tool_service.py"
click node_tool_handler "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/intelligence/tool_handler.py"
click node_tool_modules "https://github.com/johnrobins204/vox-magistri-be/tree/main/app/intelligence/tools"
click node_session_store "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/repos.py"
click node_world_mining "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/world_mining.py"
click node_world_store "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/repos.py"
click node_reference_catalog "https://github.com/johnrobins204/vox-magistri-be/tree/main/app/reference"
click node_prompt_builders "https://github.com/johnrobins204/vox-magistri-be/blob/main/app/intelligence/prompt_builders.py"

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_app_ui,node_character_editor,node_narrative_view,node_browser_api,node_browser_ws toneBlue
class node_app_factory,node_session_routes,node_intelligence_routes,node_world_routes,node_ws_routes toneAmber
class node_service_builder,node_inference,node_llm_client,node_tool_service,node_tool_handler,node_tool_modules toneMint
class node_reference_catalog,node_prompt_builders toneRose
class node_session_store,node_world_mining,node_world_store,node_player,node_ollama toneIndigo
```

## Components

### Browser App

- [Game UI](https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Character Editor](https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/components/CharacterCreator.tsx): `frontend/src/components/CharacterCreator.tsx`
- [Narrative Log](https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/components/NarrativeLog.tsx): `frontend/src/components/NarrativeLog.tsx`
- [API Client](https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Socket Client](https://github.com/johnrobins204/vox-magistri-be/blob/main/frontend/src/lib/ws.ts): `frontend/src/lib/ws.ts`

### API Surface

- [App Factory](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/factory.py): `app/factory.py`
- [Session Routes](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/session.py): `app/api/v1/session.py`
- [Intelligence Routes](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/intelligence.py): `app/api/v1/intelligence.py`
- [World Routes](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/world.py): `app/api/v1/world.py`
- [WebSocket Routes](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/api/v1/ws.py): `app/api/v1/ws.py`

### Game Runtime

- [Service Builder](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/build_services.py): `app/services/build_services.py`
- [Inference Worker](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/inference_service.py): `app/services/inference_service.py`
- [LLM Client](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/intelligence/client.py): `app/intelligence/client.py`
- [Tool Dispatcher](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/tool_service.py): `app/services/tool_service.py`
- [Command Handler](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/intelligence/tool_handler.py): `app/intelligence/tool_handler.py`
- [Game Commands](https://github.com/johnrobins204/vox-magistri-be/tree/main/app/intelligence/tools): `app/intelligence/tools`

### Game Knowledge

- [Reference Catalog](https://github.com/johnrobins204/vox-magistri-be/tree/main/app/reference): `app/reference`
- [Prompt Builders](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/intelligence/prompt_builders.py): `app/intelligence/prompt_builders.py`

### Campaign State

- [Session Store](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/repos.py): `app/services/repos.py`
- [World Mining](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/world_mining.py): `app/services/world_mining.py`
- [World Store](https://github.com/johnrobins204/vox-magistri-be/blob/main/app/services/repos.py): `app/services/repos.py`

### Other components

- **Player**
- **Ollama**

## Connections

- Player → Game UI: uses
- Game UI → Character Editor: opens (evidence: `frontend/src/App.tsx`)
- Game UI → API Client: loads and updates (evidence: `frontend/src/App.tsx`)
- Game UI → Socket Client: uses (evidence: `frontend/src/App.tsx`)
- Game UI → Narrative Log: renders (evidence: `frontend/src/App.tsx`)
- App Factory → Session Routes: registers (evidence: `app/factory.py`)
- App Factory → Intelligence Routes: registers (evidence: `app/factory.py`)
- App Factory → World Routes: registers (evidence: `app/factory.py`)
- App Factory → WebSocket Routes: registers (evidence: `app/factory.py`)
- Service Builder → Inference Worker: constructs (evidence: `app/services/build_services.py`)
- Service Builder → Tool Dispatcher: constructs (evidence: `app/services/build_services.py`)
- Service Builder → Reference Catalog: loads (evidence: `app/services/build_services.py`)
- Service Builder → World Mining: uses stoplist (evidence: `app/services/build_services.py`)
- Session Routes → Session Store: reads and writes (evidence: `app/api/v1/session.py`)
- Session Routes → Inference Worker: enqueues (evidence: `app/api/v1/session.py`)
- Intelligence Routes → Tool Dispatcher: invokes (evidence: `app/api/v1/intelligence.py`)
- World Routes → World Store: accesses (evidence: `app/api/v1/world.py`)
- Inference Worker → LLM Client: requests generation (evidence: `app/services/inference_service.py`)
- Inference Worker → Prompt Builders: builds prompts (evidence: `app/services/inference_service.py`)
- Inference Worker → Session Store: reads and writes (evidence: `app/services/inference_service.py`)
- Inference Worker → Command Handler: dispatches commands (evidence: `app/services/inference_service.py`)
- Inference Worker → World Mining: mines replies (evidence: `app/services/inference_service.py`)
- Command Handler → Game Commands: discovers and runs (evidence: `app/intelligence/tool_handler.py`)
- Tool Dispatcher → Game Commands: discovers tools (evidence: `app/services/tool_service.py`)
- World Mining → World Store: records entities (evidence: `app/services/world_mining.py`)
- LLM Client → Ollama: sends chat (evidence: `app/intelligence/client.py`)
