# nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master architecture

> Architecture diagram of the GitHub repository nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master
- Repository: https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master

## Overview

This is a browser-based, single-player AI-narrated RPG: players create a world and character, take actions, and receive rule-checked outcomes and narration that persist as campaign state. The frontend store and API client connect the UI to FastAPI routes; the application service orchestrates world generation, deterministic game rules, narration, and persistence. The README documents additional capabilities such as quests, combat, checkpoints, codex, and audio. Some subsystem links rely on README or SOURCE INDEX references rather than inspected implementations; uncertain links are omitted.

Main entry points: [`backend/app/service.py`](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/service.py) (Game service), [`backend/app/game_engine/combat_engine.py`](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/combat_engine.py) (Combat), [`frontend/lib/store.ts`](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/lib/store.ts) (Game store), [`backend/app/ai/world_generator.py`](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/world_generator.py) (World generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser experience"]
  node_game_ui["Game screens<br/>[GameLayout.tsx]"]
  node_campaign_ui["Campaign setup<br/>[page.tsx]"]
  node_store["Game store<br/>[store.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_audio["Procedural audio<br/>[audio-manager.ts]"]
end

subgraph group_api["Backend orchestration"]
  node_routes["HTTP routes<br/>[routes.py]"]
  node_service["Game service<br/>[service.py]"]
  node_app_factory["App setup<br/>[main.py]"]
end

subgraph group_world_ai["World and narration"]
  node_world_gen["World generation<br/>[world_generator.py]"]
  node_gm["Game Master<br/>[game_master.py]"]
  node_intent["Action interpretation"]
  node_llm["LLM provider<br/>[provider.py]"]
  node_world_data["World template<br/>[world_template.py]"]
end

subgraph group_rules["Deterministic game rules"]
  node_game_content["Rules content<br/>[content.py]"]
  node_action_rules["Action resolver<br/>[action_resolver.py]"]
  node_scene["Scene and travel<br/>[scene.py]"]
  node_combat["Combat<br/>[combat_engine.py]"]
  node_inventory["Inventory"]
  node_progression["Progression"]
  node_quests["Quest rules<br/>[quest_engine.py]"]
  node_shared_rules["Shared rule helpers<br/>[common.py]"]
end

subgraph group_persistence["Campaign persistence"]
  node_game_state["Game state<br/>[state.py]"]
  node_event_schema["Game events<br/>[events.py]"]
  node_db_models[("Campaign records<br/>[models.py]")]
  node_db_session[("Database session<br/>[session.py]")]
end

node_player(("Player"))

node_player -->|"configures world"| node_campaign_ui
node_player -->|"plays"| node_game_ui
node_game_ui -->|"dispatches actions"| node_store
node_campaign_ui -.->|"requests generation"| node_api_client
node_store -->|"calls"| node_api_client
node_store -->|"controls playback"| node_audio
node_api_client -.->|"HTTP requests"| node_routes
node_routes -->|"delegates"| node_service
node_app_factory -->|"registers"| node_routes
node_app_factory -->|"constructs"| node_service
node_service -->|"generates worlds"| node_world_gen
node_service -->|"requests narration"| node_gm
node_service -->|"interprets actions"| node_intent
node_world_gen -->|"generates stages"| node_llm
node_gm -->|"requests completion"| node_llm
node_intent -->|"interprets text"| node_llm
node_world_gen -->|"uses template"| node_world_data
node_service -->|"resolves actions"| node_action_rules
node_service -->|"starts scenes"| node_scene
node_action_rules -.->|"dispatches combat"| node_combat
node_action_rules -.->|"updates quests"| node_quests
node_combat -->|"uses items"| node_inventory
node_combat -->|"awards experience"| node_progression
node_combat -->|"uses helpers"| node_shared_rules
node_inventory -->|"uses helpers"| node_shared_rules
node_progression -->|"uses attributes"| node_shared_rules
node_service -->|"loads and saves"| node_game_state
node_service -->|"persists campaigns"| node_db_models
node_db_session -->|"initializes tables"| node_db_models
node_combat -->|"reads rules data"| node_game_content

click node_game_ui "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/components/GameLayout.tsx"
click node_campaign_ui "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/app/campaigns/new/page.tsx"
click node_store "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/lib/store.ts"
click node_api_client "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/lib/api.ts"
click node_audio "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/lib/audio-manager.ts"
click node_routes "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/api/routes.py"
click node_service "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/service.py"
click node_app_factory "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/main.py"
click node_world_gen "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/world_generator.py"
click node_gm "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/game_master.py"
click node_intent "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/action_interpreter.py"
click node_llm "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/provider.py"
click node_world_data "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/data/world_template.py"
click node_game_content "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/data/content.py"
click node_action_rules "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/action_resolver.py"
click node_scene "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/scene.py"
click node_combat "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/combat_engine.py"
click node_inventory "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/inventory_engine.py"
click node_progression "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/progression_engine.py"
click node_quests "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/quest_engine.py"
click node_shared_rules "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/common.py"
click node_game_state "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/models/state.py"
click node_event_schema "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/models/events.py"
click node_db_models "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/db/models.py"
click node_db_session "https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/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_game_ui,node_campaign_ui,node_store,node_api_client,node_audio toneBlue
class node_routes,node_service,node_app_factory toneAmber
class node_world_gen,node_gm,node_intent,node_llm,node_world_data toneMint
class node_game_content,node_action_rules,node_scene,node_combat,node_inventory,node_progression,node_quests,node_shared_rules toneRose
class node_game_state,node_event_schema,node_db_models,node_db_session,node_player toneIndigo
```

## Components

### Browser experience

- [Game screens](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/components/GameLayout.tsx): `frontend/components/GameLayout.tsx`
- [Campaign setup](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/app/campaigns/new/page.tsx): `frontend/app/campaigns/new/page.tsx`
- [Game store](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/lib/store.ts): `frontend/lib/store.ts`
- [API client](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Procedural audio](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/frontend/lib/audio-manager.ts): `frontend/lib/audio-manager.ts`

### Backend orchestration

- [HTTP routes](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Game service](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/service.py): `backend/app/service.py`
- [App setup](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/main.py): `backend/app/main.py`

### World and narration

- [World generation](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/world_generator.py): `backend/app/ai/world_generator.py`
- [Game Master](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/game_master.py): `backend/app/ai/game_master.py`
- [Action interpretation](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/action_interpreter.py): `backend/app/ai/action_interpreter.py`
- [LLM provider](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/ai/provider.py): `backend/app/ai/provider.py`
- [World template](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/data/world_template.py): `backend/app/data/world_template.py`

### Deterministic game rules

- [Rules content](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/data/content.py): `backend/app/data/content.py`
- [Action resolver](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/action_resolver.py): `backend/app/game_engine/action_resolver.py`
- [Scene and travel](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/scene.py): `backend/app/game_engine/scene.py`
- [Combat](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/combat_engine.py): `backend/app/game_engine/combat_engine.py`
- [Inventory](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/inventory_engine.py): `backend/app/game_engine/inventory_engine.py`
- [Progression](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/progression_engine.py): `backend/app/game_engine/progression_engine.py`
- [Quest rules](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/quest_engine.py): `backend/app/game_engine/quest_engine.py`
- [Shared rule helpers](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/game_engine/common.py): `backend/app/game_engine/common.py`

### Campaign persistence

- [Game state](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/models/state.py): `backend/app/models/state.py`
- [Game events](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/models/events.py): `backend/app/models/events.py`
- [Campaign records](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Database session](https://github.com/nikhil0074-dev/interactive-ai-rpg-worldbuilder-game-master/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Other components

- **Player**

## Connections

- Player → Campaign setup: configures world (evidence: `README.md`)
- Player → Game screens: plays (evidence: `README.md`)
- Game screens → Game store: dispatches actions (evidence: `frontend/components/GameLayout.tsx`)
- Campaign setup → API client: requests generation
- Game store → API client: calls (evidence: `frontend/lib/store.ts`)
- Game store → Procedural audio: controls playback (evidence: `frontend/lib/store.ts`)
- API client → HTTP routes: HTTP requests
- HTTP routes → Game service: delegates (evidence: `backend/app/api/routes.py`)
- App setup → HTTP routes: registers (evidence: `backend/app/main.py`)
- App setup → Game service: constructs (evidence: `backend/app/main.py`)
- Game service → World generation: generates worlds (evidence: `backend/app/service.py`)
- Game service → Game Master: requests narration (evidence: `backend/app/service.py`)
- Game service → Action interpretation: interprets actions (evidence: `backend/app/service.py`)
- World generation → LLM provider: generates stages (evidence: `backend/app/ai/world_generator.py`)
- Game Master → LLM provider: requests completion (evidence: `backend/app/ai/game_master.py`)
- Action interpretation → LLM provider: interprets text (evidence: `backend/app/ai/action_interpreter.py`)
- World generation → World template: uses template (evidence: `backend/app/ai/world_generator.py`)
- Game service → Action resolver: resolves actions (evidence: `backend/app/service.py`)
- Game service → Scene and travel: starts scenes (evidence: `backend/app/service.py`)
- Action resolver → Combat: dispatches combat
- Action resolver → Quest rules: updates quests
- Combat → Inventory: uses items (evidence: `backend/app/game_engine/combat_engine.py`)
- Combat → Progression: awards experience (evidence: `backend/app/game_engine/combat_engine.py`)
- Combat → Shared rule helpers: uses helpers (evidence: `backend/app/game_engine/combat_engine.py`)
- Inventory → Shared rule helpers: uses helpers (evidence: `backend/app/game_engine/inventory_engine.py`)
- Progression → Shared rule helpers: uses attributes (evidence: `backend/app/game_engine/progression_engine.py`)
- Game service → Game state: loads and saves (evidence: `backend/app/service.py`)
- Game service → Campaign records: persists campaigns (evidence: `backend/app/service.py`)
- Database session → Campaign records: initializes tables (evidence: `backend/app/db/session.py`)
- Combat → Rules content: reads rules data (evidence: `backend/app/game_engine/combat_engine.py`)