# chenzhou0071/ensemble architecture

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

- Interactive diagram: https://gitdiagram.com/chenzhou0071/ensemble
- Repository: https://github.com/chenzhou0071/ensemble

## Overview

Ensemble is a browser-based TRPG engine: the player joins a campaign, submits actions over WebSocket, and receives streamed GM narration and authoritative game events. A per-campaign session drives a LangGraph turn through intent, validation, checks, scene transitions, NPC responses, narration, and post-turn persistence; REST provides campaign and timeline operations. SQLite-backed branch history supports replay and rollback. The React room reduces sequenced events into narration, dice, clue, character, and NPC views. README documents budget safeguards and module-declared clues/endings; some links to unsampled internals are omitted or marked unverified.

Main entry points: [`backend/app/graph/main.py`](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/main.py) (Turn graph), [`frontend/src/views/Room.tsx`](https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/views/Room.tsx) (Game room), [`backend/app/api/session.py`](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/session.py) (Session manager), [`backend/app/api/routes.py`](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/routes.py) (Campaign REST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_lobby["Campaign lobby<br/>[Lobby.tsx]"]
  node_room["Game room<br/>[Room.tsx]"]
  node_restclient["REST client<br/>[rest.ts]"]
  node_wsclient["WebSocket client<br/>[ws.ts]"]
  node_gamestore["Event reducer<br/>[game.ts]"]
  node_gameviews["Game panels"]
end

subgraph group_service["Campaign service"]
  node_fastapi["FastAPI app<br/>[app.py]"]
  node_campaignapi["Campaign REST<br/>[routes.py]"]
  node_websocket["WebSocket endpoint<br/>[ws.py]"]
  node_session["Session manager<br/>[session.py]"]
  node_eventbus["Sequenced event bus<br/>[events.py]"]
end

subgraph group_engine["Turn engine"]
  node_turngraph["Turn graph<br/>[main.py]"]
  node_gm["GM decisions<br/>[gm.py]"]
  node_turnrules["Turn resolution<br/>[turn.py]"]
  node_npcagent["NPC agents<br/>[npc.py]"]
  node_rules["Dice and rules"]
  node_content["Module content<br/>[loader.py]"]
end

subgraph group_state["Memory and persistence"]
  node_journal["Campaign memory<br/>[journal.py]"]
  node_background["Summary queue<br/>[tasks.py]"]
  node_repository["Campaign repository<br/>[repo.py]"]
  node_sqlite[("SQLite store<br/>[db.py]")]
  node_rollback["Branch restore<br/>[fork.py]"]
end

subgraph group_providers["Model services"]
  node_llm["LLM client<br/>[client.py]"]
end

node_player(("Player"))
node_modelservice{{"LLM providers"}}

node_player -->|"starts campaign"| node_lobby
node_app -->|"routes to"| node_lobby
node_app -->|"routes to"| node_room
node_lobby -->|"requests campaigns"| node_restclient
node_restclient -.->|"calls REST"| node_campaignapi
node_room -->|"loads module"| node_restclient
node_room -->|"opens session"| node_wsclient
node_player -->|"submits action"| node_room
node_wsclient -.->|"sends input"| node_websocket
node_fastapi -->|"registers routes"| node_campaignapi
node_fastapi -->|"registers endpoint"| node_websocket
node_websocket -.->|"dispatches input"| node_session
node_campaignapi -->|"reads and writes"| node_repository
node_campaignapi -->|"loads module"| node_content
node_campaignapi -->|"forks branch"| node_rollback
node_session -->|"drives graph"| node_turngraph
node_session -->|"publishes events"| node_eventbus
node_session -.->|"reads snapshots"| node_repository
node_eventbus -.->|"broadcasts events"| node_websocket
node_websocket -.->|"streams events"| node_wsclient
node_wsclient -->|"delivers events"| node_gamestore
node_room -->|"reads state"| node_gamestore
node_room -->|"renders panels"| node_gameviews
node_turngraph -->|"dispatches decisions"| node_gm
node_turngraph -->|"dispatches resolution"| node_turnrules
node_turngraph -->|"dispatches NPC work"| node_npcagent
node_gm -->|"requests completions"| node_llm
node_npcagent -->|"requests completions"| node_llm
node_turnrules -->|"uses checks"| node_rules
node_turngraph -.->|"uses module"| node_content
node_llm -.->|"calls model API"| node_modelservice
node_turngraph -.->|"persists turns"| node_repository
node_turngraph -.->|"queries memory"| node_journal
node_session -.->|"schedules summaries"| node_background
node_journal -->|"reads and appends"| node_repository
node_repository -.->|"stores records"| node_sqlite

click node_app "https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/App.tsx"
click node_lobby "https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/views/Lobby.tsx"
click node_room "https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/views/Room.tsx"
click node_restclient "https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/api/rest.ts"
click node_wsclient "https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/api/ws.ts"
click node_gamestore "https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/stores/game.ts"
click node_gameviews "https://github.com/chenzhou0071/ensemble/tree/main/frontend/src/components"
click node_fastapi "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/app.py"
click node_campaignapi "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/routes.py"
click node_websocket "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/ws.py"
click node_session "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/session.py"
click node_eventbus "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/events.py"
click node_turngraph "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/main.py"
click node_gm "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/nodes/gm.py"
click node_turnrules "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/nodes/turn.py"
click node_npcagent "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/npc.py"
click node_rules "https://github.com/chenzhou0071/ensemble/tree/main/backend/app/rules"
click node_content "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/content/loader.py"
click node_llm "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/llm/client.py"
click node_journal "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/memory/journal.py"
click node_background "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/tasks.py"
click node_repository "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/storage/repo.py"
click node_sqlite "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/storage/db.py"
click node_rollback "https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/fork.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,node_lobby,node_room,node_restclient,node_wsclient,node_gamestore,node_gameviews toneBlue
class node_fastapi,node_campaignapi,node_websocket,node_session,node_eventbus toneAmber
class node_turngraph,node_gm,node_turnrules,node_npcagent,node_rules,node_content toneMint
class node_journal,node_background,node_repository,node_sqlite,node_rollback toneRose
class node_llm,node_player,node_modelservice toneIndigo
```

## Components

### Browser experience

- [App routing](https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Campaign lobby](https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/views/Lobby.tsx): `frontend/src/views/Lobby.tsx`
- [Game room](https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/views/Room.tsx): `frontend/src/views/Room.tsx`
- [REST client](https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/api/rest.ts): `frontend/src/api/rest.ts`
- [WebSocket client](https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/api/ws.ts): `frontend/src/api/ws.ts`
- [Event reducer](https://github.com/chenzhou0071/ensemble/blob/main/frontend/src/stores/game.ts): `frontend/src/stores/game.ts`
- [Game panels](https://github.com/chenzhou0071/ensemble/tree/main/frontend/src/components): `frontend/src/components`

### Campaign service

- [FastAPI app](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/app.py): `backend/app/api/app.py`
- [Campaign REST](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [WebSocket endpoint](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/ws.py): `backend/app/api/ws.py`
- [Session manager](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/session.py): `backend/app/api/session.py`
- [Sequenced event bus](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/api/events.py): `backend/app/api/events.py`

### Turn engine

- [Turn graph](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/main.py): `backend/app/graph/main.py`
- [GM decisions](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/nodes/gm.py): `backend/app/graph/nodes/gm.py`
- [Turn resolution](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/nodes/turn.py): `backend/app/graph/nodes/turn.py`
- [NPC agents](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/npc.py): `backend/app/graph/npc.py`
- [Dice and rules](https://github.com/chenzhou0071/ensemble/tree/main/backend/app/rules): `backend/app/rules`
- [Module content](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/content/loader.py): `backend/app/content/loader.py`

### Memory and persistence

- [Campaign memory](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/memory/journal.py): `backend/app/memory/journal.py`
- [Summary queue](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/tasks.py): `backend/app/tasks.py`
- [Campaign repository](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/storage/repo.py): `backend/app/storage/repo.py`
- [SQLite store](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/storage/db.py): `backend/app/storage/db.py`
- [Branch restore](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/graph/fork.py): `backend/app/graph/fork.py`

### Model services

- [LLM client](https://github.com/chenzhou0071/ensemble/blob/main/backend/app/llm/client.py): `backend/app/llm/client.py`

### Other components

- **Player**
- **LLM providers**

## Connections

- Player → Campaign lobby: starts campaign (evidence: `README.md`)
- App routing → Campaign lobby: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Game room: routes to (evidence: `frontend/src/App.tsx`)
- Campaign lobby → REST client: requests campaigns (evidence: `frontend/src/views/Lobby.tsx`)
- REST client → Campaign REST: calls REST (evidence: `README.md`)
- Game room → REST client: loads module (evidence: `frontend/src/views/Room.tsx`)
- Game room → WebSocket client: opens session (evidence: `frontend/src/views/Room.tsx`)
- Player → Game room: submits action (evidence: `README.md`)
- WebSocket client → WebSocket endpoint: sends input (evidence: `README.md`)
- FastAPI app → Campaign REST: registers routes (evidence: `backend/app/api/app.py`)
- FastAPI app → WebSocket endpoint: registers endpoint (evidence: `backend/app/api/app.py`)
- WebSocket endpoint → Session manager: dispatches input (evidence: `README.md`)
- Campaign REST → Campaign repository: reads and writes (evidence: `backend/app/api/routes.py`)
- Campaign REST → Module content: loads module (evidence: `backend/app/api/routes.py`)
- Campaign REST → Branch restore: forks branch (evidence: `backend/app/api/routes.py`)
- Session manager → Turn graph: drives graph (evidence: `backend/app/api/session.py`)
- Session manager → Sequenced event bus: publishes events (evidence: `backend/app/api/session.py`)
- Session manager → Campaign repository: reads snapshots (evidence: `README.md`)
- Sequenced event bus → WebSocket endpoint: broadcasts events (evidence: `README.md`)
- WebSocket endpoint → WebSocket client: streams events (evidence: `README.md`)
- WebSocket client → Event reducer: delivers events (evidence: `frontend/src/views/Room.tsx`)
- Game room → Event reducer: reads state (evidence: `frontend/src/views/Room.tsx`)
- Game room → Game panels: renders panels (evidence: `frontend/src/views/Room.tsx`)
- Turn graph → GM decisions: dispatches decisions (evidence: `backend/app/graph/main.py`)
- Turn graph → Turn resolution: dispatches resolution (evidence: `backend/app/graph/main.py`)
- Turn graph → NPC agents: dispatches NPC work (evidence: `backend/app/graph/main.py`)
- GM decisions → LLM client: requests completions (evidence: `backend/app/graph/nodes/gm.py`)
- NPC agents → LLM client: requests completions (evidence: `backend/app/graph/npc.py`)
- Turn resolution → Dice and rules: uses checks (evidence: `backend/app/graph/nodes/turn.py`)
- Turn graph → Module content: uses module
- LLM client → LLM providers: calls model API (evidence: `README.md`)
- Turn graph → Campaign repository: persists turns (evidence: `README.md`)
- Turn graph → Campaign memory: queries memory
- Session manager → Summary queue: schedules summaries (evidence: `backend/app/api/session.py`)
- Campaign memory → Campaign repository: reads and appends (evidence: `backend/app/memory/journal.py`)
- Campaign repository → SQLite store: stores records (evidence: `README.md`)
