How chenzhou0071/ensemble works
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: main.py Turn graph · Room.tsx Game room · session.py Session manager · routes.py Campaign REST
Components 26
Browser experience
- App routing
frontend/src/App.tsx - Campaign lobby
frontend/src/views/Lobby.tsx - Game room
frontend/src/views/Room.tsx - REST client
frontend/src/api/rest.ts - WebSocket client
frontend/src/api/ws.ts - Event reducer
frontend/src/stores/game.ts - Game panels
frontend/src/components
Campaign service
- FastAPI app
backend/app/api/app.py - Campaign REST
backend/app/api/routes.py - WebSocket endpoint
backend/app/api/ws.py - Session manager
backend/app/api/session.py - Sequenced event bus
backend/app/api/events.py
Turn engine
- Turn graph
backend/app/graph/main.py - GM decisions
backend/app/graph/nodes/gm.py - Turn resolution
backend/app/graph/nodes/turn.py - NPC agents
backend/app/graph/npc.py - Dice and rules
backend/app/rules - Module content
backend/app/content/loader.py
Memory and persistence
- Campaign memory
backend/app/memory/journal.py - Summary queue
backend/app/tasks.py - Campaign repository
backend/app/storage/repo.py - SQLite store
backend/app/storage/db.py - Branch restore
backend/app/graph/fork.py
Model services
- LLM client
backend/app/llm/client.py
Other components
- Player
- LLM providers
Connections 36
- Player → Campaign lobby: starts campaign
README.md - App routing → Campaign lobby: routes to
frontend/src/App.tsx - App routing → Game room: routes to
frontend/src/App.tsx - Campaign lobby → REST client: requests campaigns
frontend/src/views/Lobby.tsx - REST client → Campaign REST: calls REST
README.md - Game room → REST client: loads module
frontend/src/views/Room.tsx - Game room → WebSocket client: opens session
frontend/src/views/Room.tsx - Player → Game room: submits action
README.md - WebSocket client → WebSocket endpoint: sends input
README.md - FastAPI app → Campaign REST: registers routes
backend/app/api/app.py - FastAPI app → WebSocket endpoint: registers endpoint
backend/app/api/app.py - WebSocket endpoint → Session manager: dispatches input
README.md - Campaign REST → Campaign repository: reads and writes
backend/app/api/routes.py - Campaign REST → Module content: loads module
backend/app/api/routes.py - Campaign REST → Branch restore: forks branch
backend/app/api/routes.py - Session manager → Turn graph: drives graph
backend/app/api/session.py - Session manager → Sequenced event bus: publishes events
backend/app/api/session.py - Session manager → Campaign repository: reads snapshots
README.md - Sequenced event bus → WebSocket endpoint: broadcasts events
README.md - WebSocket endpoint → WebSocket client: streams events
README.md - WebSocket client → Event reducer: delivers events
frontend/src/views/Room.tsx - Game room → Event reducer: reads state
frontend/src/views/Room.tsx - Game room → Game panels: renders panels
frontend/src/views/Room.tsx - Turn graph → GM decisions: dispatches decisions
backend/app/graph/main.py - Turn graph → Turn resolution: dispatches resolution
backend/app/graph/main.py - Turn graph → NPC agents: dispatches NPC work
backend/app/graph/main.py - GM decisions → LLM client: requests completions
backend/app/graph/nodes/gm.py - NPC agents → LLM client: requests completions
backend/app/graph/npc.py - Turn resolution → Dice and rules: uses checks
backend/app/graph/nodes/turn.py - Turn graph → Module content: uses module
- LLM client → LLM providers: calls model API
README.md - Turn graph → Campaign repository: persists turns
README.md - Turn graph → Campaign memory: queries memory
- Session manager → Summary queue: schedules summaries
backend/app/api/session.py - Campaign memory → Campaign repository: reads and appends
backend/app/memory/journal.py - Campaign repository → SQLite store: stores records
README.md