# jianwang97/jubensha-ai architecture

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

- Interactive diagram: https://gitdiagram.com/jianwang97/jubensha-ai
- Repository: https://github.com/jianwang97/jubensha-ai

## Overview

JubenSha-ai is a web-based AI murder-mystery game: users manage or generate scripts, then run an AI-driven case through investigation, discussion, voting, and revelation, with live updates and optional speech and image generation. The map preserves script authoring, gameplay, history, and media as distinct product branches. The README documents these capabilities; sampled source confirms selected game, agent, image, storage, authentication, and persistence behavior, but not every route-to-service connection.

Main entry points: [`backend/src/core/game_engine.py`](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/game_engine.py) (Game engine), [`backend/src/core/server.py`](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/server.py) (HTTP API), [`backend/src/api/routes/image_generation_routes.py`](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/image_generation_routes.py) (Image API), [`backend/src/services/llm_service.py`](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/llm_service.py) (LLM service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web app<br/>[index.tsx]"]
  node_scriptui["Script tools<br/>[index.tsx]"]
  node_historyui["History UI<br/>[index.tsx]"]
  node_authclient["Auth client<br/>[authService.ts]"]
end

subgraph group_api["API and authoring"]
  node_backend["HTTP API<br/>[server.py]"]
  node_authroute["Auth routes<br/>[auth_routes.py]"]
  node_authsvc["Auth service<br/>[auth_service.py]"]
  node_scriptroute["Script routes<br/>[script_routes.py]"]
  node_scriptgen["Script generation"]
  node_scriptedit["Script editing"]
  node_gameroute["Game routes<br/>[game_routes.py]"]
  node_history["Game history"]
  node_imageroute["Image API"]
end

subgraph group_game["Game runtime"]
  node_engine["Game engine<br/>[game_engine.py]"]
  node_agents["Character agents"]
  node_evidence["Evidence manager"]
  node_voting["Voting manager<br/>[voting_manager.py]"]
  node_ws["Live sync"]
end

subgraph group_ai["AI and media"]
  node_llm["LLM service<br/>[llm_service.py]"]
  node_tts["TTS service<br/>[tts_service.py]"]
  node_image["Image generation"]
end

subgraph group_data["Persistence"]
  node_storage["Asset storage<br/>[storage.py]"]
  node_scriptrepo["Script repository"]
  node_sessionrepo["Session repository"]
  node_database[("Relational database<br/>[session.py]")]
end

node_player(("Player / author"))
node_imageprovider["Image provider"]
node_speechprovider["Speech provider"]
node_llmprovider["LLM provider"]

node_player -->|"plays"| node_webapp
node_player -->|"authors"| node_scriptui
node_webapp -->|"requests game"| node_backend
node_scriptui -->|"requests scripts"| node_backend
node_historyui -->|"requests history"| node_backend
node_authclient -->|"calls auth API"| node_authroute
node_backend -->|"dispatches"| node_authroute
node_authroute -->|"authenticates"| node_authsvc
node_backend -->|"dispatches"| node_scriptroute
node_scriptroute -->|"reads / writes"| node_scriptrepo
node_scriptui -->|"generates scripts"| node_scriptgen
node_scriptui -->|"edits scripts"| node_scriptedit
node_scriptroute -->|"generates content"| node_scriptgen
node_scriptroute -->|"edits content"| node_scriptedit
node_scriptgen -->|"requests completion"| node_llm
node_scriptedit -->|"requests completion"| node_llm
node_backend -->|"dispatches"| node_gameroute
node_gameroute -->|"controls game"| node_engine
node_engine -->|"requests character turns"| node_agents
node_agents -->|"requests responses"| node_llm
node_engine -->|"tracks discoveries"| node_evidence
node_engine -->|"manages votes"| node_voting
node_engine -->|"broadcasts state"| node_ws
node_engine -->|"persists sessions"| node_sessionrepo
node_history -->|"reads session events"| node_sessionrepo
node_sessionrepo -->|"reads / writes"| node_database
node_scriptrepo -->|"reads / writes"| node_database
node_backend -->|"dispatches"| node_imageroute
node_imageroute -->|"requests image"| node_image
node_imageroute -->|"optimizes prompt"| node_llm
node_imageroute -->|"stores generated asset"| node_storage
node_imageroute -->|"loads script details"| node_scriptrepo
node_image -.->|"generates image"| node_imageprovider
node_llm -.->|"completes prompts"| node_llmprovider
node_engine -.->|"requests speech"| node_tts
node_tts -.->|"synthesizes speech"| node_speechprovider
node_historyui -->|"retrieves replays"| node_history

click node_webapp "https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/pages/game/index.tsx"
click node_scriptui "https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/pages/script-manager/index.tsx"
click node_historyui "https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/pages/game-history/index.tsx"
click node_authclient "https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/services/authService.ts"
click node_backend "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/server.py"
click node_authroute "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/auth_routes.py"
click node_authsvc "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/auth_service.py"
click node_scriptroute "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/script_routes.py"
click node_scriptgen "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/script_generation_service.py"
click node_scriptedit "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/script_editor_service.py"
click node_gameroute "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/game_routes.py"
click node_history "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/game_history_service.py"
click node_engine "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/game_engine.py"
click node_agents "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/agents/character_agent_manager.py"
click node_evidence "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/evidence_manager.py"
click node_voting "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/voting_manager.py"
click node_ws "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/websocket_server.py"
click node_llm "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/llm_service.py"
click node_tts "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/tts_service.py"
click node_image "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/image_generation_service.py"
click node_imageroute "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/image_generation_routes.py"
click node_storage "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/storage.py"
click node_scriptrepo "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/db/repositories/script_repository.py"
click node_sessionrepo "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/db/repositories/game_session_repository.py"
click node_database "https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/db/session.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_webapp,node_scriptui,node_historyui,node_authclient toneBlue
class node_backend,node_authroute,node_authsvc,node_scriptroute,node_scriptgen,node_scriptedit,node_gameroute,node_history,node_imageroute toneAmber
class node_engine,node_agents,node_evidence,node_voting,node_ws toneMint
class node_llm,node_tts,node_image toneRose
class node_storage,node_scriptrepo,node_sessionrepo,node_database,node_player,node_imageprovider,node_speechprovider,node_llmprovider toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/pages/game/index.tsx): `frontend/src/pages/game/index.tsx`
- [Script tools](https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/pages/script-manager/index.tsx): `frontend/src/pages/script-manager/index.tsx`
- [History UI](https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/pages/game-history/index.tsx): `frontend/src/pages/game-history/index.tsx`
- [Auth client](https://github.com/jianwang97/jubensha-ai/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`

### API and authoring

- [HTTP API](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/server.py): `backend/src/core/server.py`
- [Auth routes](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/auth_routes.py): `backend/src/api/routes/auth_routes.py`
- [Auth service](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/auth_service.py): `backend/src/services/auth_service.py`
- [Script routes](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/script_routes.py): `backend/src/api/routes/script_routes.py`
- [Script generation](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/script_generation_service.py): `backend/src/services/script_generation_service.py`
- [Script editing](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/script_editor_service.py): `backend/src/services/script_editor_service.py`
- [Game routes](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/game_routes.py): `backend/src/api/routes/game_routes.py`
- [Game history](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/game_history_service.py): `backend/src/services/game_history_service.py`
- [Image API](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/api/routes/image_generation_routes.py): `backend/src/api/routes/image_generation_routes.py`

### Game runtime

- [Game engine](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/game_engine.py): `backend/src/core/game_engine.py`
- [Character agents](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/agents/character_agent_manager.py): `backend/src/agents/character_agent_manager.py`
- [Evidence manager](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/evidence_manager.py): `backend/src/core/evidence_manager.py`
- [Voting manager](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/voting_manager.py): `backend/src/core/voting_manager.py`
- [Live sync](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/websocket_server.py): `backend/src/core/websocket_server.py`

### AI and media

- [LLM service](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/llm_service.py): `backend/src/services/llm_service.py`
- [TTS service](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/tts_service.py): `backend/src/services/tts_service.py`
- [Image generation](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/services/image_generation_service.py): `backend/src/services/image_generation_service.py`

### Persistence

- [Asset storage](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/core/storage.py): `backend/src/core/storage.py`
- [Script repository](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/db/repositories/script_repository.py): `backend/src/db/repositories/script_repository.py`
- [Session repository](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/db/repositories/game_session_repository.py): `backend/src/db/repositories/game_session_repository.py`
- [Relational database](https://github.com/jianwang97/jubensha-ai/blob/main/backend/src/db/session.py): `backend/src/db/session.py`

### Other components

- **Player / author**
- **Image provider**
- **Speech provider**
- **LLM provider**

## Connections

- Player / author → Web app: plays
- Player / author → Script tools: authors
- Web app → HTTP API: requests game
- Script tools → HTTP API: requests scripts
- History UI → HTTP API: requests history
- Auth client → Auth routes: calls auth API
- HTTP API → Auth routes: dispatches
- Auth routes → Auth service: authenticates
- HTTP API → Script routes: dispatches
- Script routes → Script repository: reads / writes
- Script tools → Script generation: generates scripts
- Script tools → Script editing: edits scripts
- Script routes → Script generation: generates content
- Script routes → Script editing: edits content
- Script generation → LLM service: requests completion
- Script editing → LLM service: requests completion
- HTTP API → Game routes: dispatches
- Game routes → Game engine: controls game
- Game engine → Character agents: requests character turns
- Character agents → LLM service: requests responses
- Game engine → Evidence manager: tracks discoveries
- Game engine → Voting manager: manages votes
- Game engine → Live sync: broadcasts state
- Game engine → Session repository: persists sessions
- Game history → Session repository: reads session events
- Session repository → Relational database: reads / writes
- Script repository → Relational database: reads / writes
- HTTP API → Image API: dispatches
- Image API → Image generation: requests image
- Image API → LLM service: optimizes prompt
- Image API → Asset storage: stores generated asset
- Image API → Script repository: loads script details
- Image generation → Image provider: generates image
- LLM service → LLM provider: completes prompts
- Game engine → TTS service: requests speech
- TTS service → Speech provider: synthesizes speech
- History UI → Game history: retrieves replays