# 4thfever/cultivation-world-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/4thfever/cultivation-world-simulator
- Repository: https://github.com/4thfever/cultivation-world-simulator

## Overview

Cultivation World Simulator is an AI-driven cultivation-world simulation in which the player observes the world as its “Heavenly Dao” and can intervene. The main loop runs from the web UI or external client through read-only queries and controlled commands, then back to refreshed world state and events. The backend also advances autonomous avatar, sect, and world simulation; roleplay choices can involve the player, while LLM services drive AI behavior. The README documents these capabilities; links for unsampled subsystems are limited to documented flows and the visible module structure.

Main entry points: [`src/sim/simulator_engine/phase_runner.py`](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/sim/simulator_engine/phase_runner.py) (Phase Engine), [`web/src/App.vue`](https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/App.vue) (Game UI), [`web/src/api/index.ts`](https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/api/index.ts) (Web API Client), [`src/server/services/game_query_service.py`](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/services/game_query_service.py) (Query Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Player Interfaces"]
  node_webui["Game UI<br/>[App.vue]"]
  node_gameview["World View<br/>[GameCanvas.vue]"]
  node_webapi["Web API Client<br/>[index.ts]"]
end

subgraph group_api["Control API"]
  node_queryapi["Read Queries<br/>[query.py]"]
  node_commandapi["Game Commands<br/>[command.py]"]
  node_settingsapi["Settings API<br/>[settings.py]"]
  node_queryservice["Query Service"]
  node_commandservice["Command Service"]
end

subgraph group_simulation["World Simulation"]
  node_runtime["Game Runtime<br/>[session.py]"]
  node_loop["Simulation Loop<br/>[runner.py]"]
  node_engine["Phase Engine<br/>[phase_runner.py]"]
end

subgraph group_domain["World Systems"]
  node_avatar["Avatar Agents<br/>[core.py]"]
  node_actions["Avatar Actions<br/>[action_runtime.py]"]
  node_sects["Sect Dynamics<br/>[sect_manager.py]"]
  node_world["World Model<br/>[world.py]"]
  node_events[("Event History<br/>[event_storage.py]")]
  node_poi["Points of Interest<br/>[manager.py]"]
end

subgraph group_services["Runtime Services"]
  node_roleplay["Roleplay Service"]
  node_choice["Choice Engine<br/>[engine.py]"]
  node_llm["LLM Client<br/>[client.py]"]
  node_settings["Settings Service"]
  node_saves["Save Load<br/>[save_game.py]"]
  node_epic["Epic Metrics<br/>[epicRuntime.ts]"]
end

node_player(("Player"))
node_external(("External Agent"))

node_player -->|"interacts"| node_webui
node_webui -->|"renders"| node_gameview
node_webui -->|"requests"| node_webapi
node_webapi -->|"queries"| node_queryapi
node_webapi -->|"commands"| node_commandapi
node_external -->|"queries"| node_queryapi
node_external -->|"commands"| node_commandapi
node_queryapi -->|"delegates"| node_queryservice
node_queryservice -->|"reads state"| node_runtime
node_queryservice -->|"queries events"| node_events
node_commandapi -->|"delegates"| node_commandservice
node_commandservice -->|"controls"| node_runtime
node_settingsapi -->|"manages"| node_settings
node_loop -->|"runs phases"| node_engine
node_engine -->|"advances"| node_world
node_engine -->|"simulates"| node_avatar
node_engine -->|"updates"| node_sects
node_avatar -->|"performs"| node_actions
node_engine -->|"updates"| node_poi
node_engine -->|"records events"| node_events
node_choice -->|"requests decision"| node_llm
node_choice -.->|"waits for choice"| node_roleplay
node_roleplay -->|"generates dialogue"| node_llm
node_saves -->|"loads and saves"| node_runtime
node_epic -.->|"reports sessions"| node_external

click node_webui "https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/App.vue"
click node_gameview "https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/components/game/GameCanvas.vue"
click node_webapi "https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/api/index.ts"
click node_queryapi "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/api/public_v1/query.py"
click node_commandapi "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/api/public_v1/command.py"
click node_settingsapi "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/api/settings.py"
click node_queryservice "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/services/game_query_service.py"
click node_commandservice "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/services/game_command_service.py"
click node_runtime "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/runtime/session.py"
click node_loop "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/loop/runner.py"
click node_engine "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/sim/simulator_engine/phase_runner.py"
click node_avatar "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/core/avatar/core.py"
click node_actions "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/action_runtime.py"
click node_sects "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/sim/managers/sect_manager.py"
click node_world "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/core/world.py"
click node_events "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/event_storage.py"
click node_poi "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/poi/manager.py"
click node_roleplay "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/services/roleplay_service.py"
click node_choice "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/systems/single_choice/engine.py"
click node_llm "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/utils/llm/client.py"
click node_settings "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/config/settings_service.py"
click node_saves "https://github.com/4thfever/cultivation-world-simulator/blob/main/src/sim/save/save_game.py"
click node_epic "https://github.com/4thfever/cultivation-world-simulator/blob/main/desktop/src/epicRuntime.ts"

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_webui,node_gameview,node_webapi toneBlue
class node_queryapi,node_commandapi,node_settingsapi,node_queryservice,node_commandservice toneAmber
class node_runtime,node_loop,node_engine toneMint
class node_avatar,node_actions,node_sects,node_world,node_events,node_poi toneRose
class node_roleplay,node_choice,node_llm,node_settings,node_saves,node_epic,node_player,node_external toneIndigo
```

## Components

### Player Interfaces

- [Game UI](https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/App.vue): `web/src/App.vue`
- [World View](https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/components/game/GameCanvas.vue): `web/src/components/game/GameCanvas.vue`
- [Web API Client](https://github.com/4thfever/cultivation-world-simulator/blob/main/web/src/api/index.ts): `web/src/api/index.ts`

### Control API

- [Read Queries](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/api/public_v1/query.py): `src/server/api/public_v1/query.py`
- [Game Commands](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/api/public_v1/command.py): `src/server/api/public_v1/command.py`
- [Settings API](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/api/settings.py): `src/server/api/settings.py`
- [Query Service](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/services/game_query_service.py): `src/server/services/game_query_service.py`
- [Command Service](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/services/game_command_service.py): `src/server/services/game_command_service.py`

### World Simulation

- [Game Runtime](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/runtime/session.py): `src/server/runtime/session.py`
- [Simulation Loop](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/loop/runner.py): `src/server/loop/runner.py`
- [Phase Engine](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/sim/simulator_engine/phase_runner.py): `src/sim/simulator_engine/phase_runner.py`

### World Systems

- [Avatar Agents](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/core/avatar/core.py): `src/classes/core/avatar/core.py`
- [Avatar Actions](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/action_runtime.py): `src/classes/action_runtime.py`
- [Sect Dynamics](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/sim/managers/sect_manager.py): `src/sim/managers/sect_manager.py`
- [World Model](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/core/world.py): `src/classes/core/world.py`
- [Event History](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/event_storage.py): `src/classes/event_storage.py`
- [Points of Interest](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/classes/poi/manager.py): `src/classes/poi/manager.py`

### Runtime Services

- [Roleplay Service](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/server/services/roleplay_service.py): `src/server/services/roleplay_service.py`
- [Choice Engine](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/systems/single_choice/engine.py): `src/systems/single_choice/engine.py`
- [LLM Client](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/utils/llm/client.py): `src/utils/llm/client.py`
- [Settings Service](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/config/settings_service.py): `src/config/settings_service.py`
- [Save Load](https://github.com/4thfever/cultivation-world-simulator/blob/main/src/sim/save/save_game.py): `src/sim/save/save_game.py`
- [Epic Metrics](https://github.com/4thfever/cultivation-world-simulator/blob/main/desktop/src/epicRuntime.ts): `desktop/src/epicRuntime.ts`

### Other components

- **Player**
- **External Agent**

## Connections

- Player → Game UI: interacts
- Game UI → World View: renders
- Game UI → Web API Client: requests
- Web API Client → Read Queries: queries
- Web API Client → Game Commands: commands
- External Agent → Read Queries: queries
- External Agent → Game Commands: commands
- Read Queries → Query Service: delegates
- Query Service → Game Runtime: reads state
- Query Service → Event History: queries events
- Game Commands → Command Service: delegates
- Command Service → Game Runtime: controls
- Settings API → Settings Service: manages
- Simulation Loop → Phase Engine: runs phases
- Phase Engine → World Model: advances
- Phase Engine → Avatar Agents: simulates
- Phase Engine → Sect Dynamics: updates
- Avatar Agents → Avatar Actions: performs
- Phase Engine → Points of Interest: updates
- Phase Engine → Event History: records events
- Choice Engine → LLM Client: requests decision
- Choice Engine → Roleplay Service: waits for choice
- Roleplay Service → LLM Client: generates dialogue
- Save Load → Game Runtime: loads and saves
- Epic Metrics → External Agent: reports sessions