# newbikscube/chatbotrpg architecture

> Architecture diagram of the GitHub repository newbikscube/chatbotrpg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/newbikscube/chatbotrpg
- Repository: https://github.com/newbikscube/chatbotrpg

## Overview

##### Project type and purpose
- This is a standalone, desktop “thick‐client” application written in Python using PyQt5 for its GUI.
- Its purpose is to provide an interactive text‐based RPG engine: a UI front end for chat, world editing, rule and character management, and an AI-backed game logic core that persists data as JSON files.

##### File structure
- Top-level assets:
- Demo.zip (sample game data)
- config.json (API keys, settings)
- sounds/ (UI and game sound effects)
- START.bat (Windows launcher)
- src/ – main application code:
- chatBotRPG.py – entry point: initializes the app, loads config, and starts the main window.
- config.py – loads and exposes configuration (API keys, model settings).
- core/ – “controller” and “model” logic for UI behaviors (splitters, tab management, stylesheets), game flow (splash, intro, game over), inference, memory, rule triggers, and utilities.
- editor_panel/ – UI for game‐building tools: world editor (canvas, toolbars), actor/inventory/rules/time managers, etc.
- player_panel/ – UI for the player’s view: chat window, world map, right splitter controls.
- generate/ – modules to procedurally generate actors, settings, summaries, and random lists.
- rules/ – the rules engine: loading/applying rules, evaluating conditions, triggering screen effects and timer‐based rules.
- scribe/ – the built-in AI assistant module for helping creators via agent_chat.
- There is no centralized database – data persistence is via JSON files in /data/ (unpacked from Demo.zip).

##### README for technical insights
- Confirms PyQt5 UI, JSON-based persistence, OpenRouter.ai (and other LLM) integration.
- Emphasizes modular game-building toolkits: Worlds, Time Passage, Character Management, Rules Engine, Keywords Matching, Inventory, Random Lists, Scribe.
- Notes that game state is stored in /data/<game_name>/… and snapshots in /saves/.

##### Main components
a. Frontend (UI Layer)
- ChatWindow (core/chatBotRPG)
- EditorPanel (editor_panel/*)
- PlayerPanel (player_panel/*)
- SoundPlayer (sounds/*.mp3)
b. Application Logic (Controller Layer)
- Core Engine (core/*): splitters, tab manager, UI widgets, game_intro, move_character, process_keywords, memory.
- Rules Engine (rules/*): apply_rules, rule_evaluator, timer_rules_manager.
- Generation Modules (generate/*): generate_actor, generate_setting, generate_summary, random lists.
- Scribe Agent (scribe/agent_chat.py): helper AI agent for game creation.
c. Data Persistence (Model Layer)
- JSON file store in /data/ and /saves/ (represented as a “document store”).
- Config Store (config.json).
d. External Services
- LLM API (OpenRouter.ai, Google GenAI, etc.) – invoked by core.character_inference and scribe.
- File System (Demo.zip unpack, sounds folder).
e. Runtime orchestrator
- chatBotRPG.py ties together UI, core, rules, generate, and scribe, handling event loop and high-level flows.

##### Relationships and interactions
- User interacts with UI (ChatWindow, EditorPanel, PlayerPanel).
- UI events → Core Engine controllers (process user input, trigger splitters, update UI).
- Core Engine → Rules Engine for conditional logic and game‐over triggers.
- Core Engine / Rules Engine → LLM Inference (via character_inference or make_inference) with prompts from process_keywords.
- Generation Modules may be invoked by EditorPanel or Scribe to produce new world/actor/rule content, then stored as JSON.
- All state changes → persisted to JSON files; saves are folder snapshots.
- UI sound events → SoundPlayer reads from sounds/ folder.
- Scribe Agent can call LLM, return suggestions, integrated into EditorPanel UI.

##### Architectural patterns and design principles
- MVC/MVP style separation:
- View: PyQt5 UI panels
- Controller: core/* modules orchestrating events, rules, and inference
- Model: JSON persistence, in-memory game state in memory.py
- Modular plugin-like structure: editor_panel, player_panel, generate, rules, scribe appear as well-defined packages.
- Clear separation of concerns: UI styling (apply_stylesheet), UI layout (splitters), game logic (core and rules), generation, persistence, external calls.

##### Elements
- Clear labels:
- ChatWindow, EditorPanel, PlayerPanel
- CoreEngine, RulesEngine, GenerationModules, ScribeAgent
- JSON Data Store, Config Store, Sound Resources
- External LLM Service
- UI → CoreEngine (user actions)
- CoreEngine → RulesEngine (evaluate conditions)
- CoreEngine/RulesEngine → LLM API (inference calls)
- GenerationModules → JSON Store (write new game files)
- UI → SoundPlayer → sounds/*.mp3
- Blue rectangles for UI components
- Green rectangles for business logic modules
- Yellow parallelogram for external service (LLM API)
- Rounded rectangles for utility modules (config, sound).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        ChatWindow["ChatWindow"]:::ui
        EditorPanel["EditorPanel"]:::ui
        PlayerPanel["PlayerPanel"]:::ui
        SoundPlayer["SoundPlayer"]:::utility
    end

    %% Controller Layer
    subgraph "Controller Layer"
        CoreEngine["Core Engine"]:::logic
        split1["top_splitter.py"]:::logic
        split2["bottom_splitter.py"]:::logic
        split3["themed_splitter.py"]:::logic
        tabMan["tab_manager.py"]:::logic
        uiWidgets["ui_widgets.py"]:::logic
        applyStyle["apply_stylesheet.py"]:::logic
        splash["splash_screen.py"]:::logic
        intro["game_intro.py"]:::logic
        over["game_over.py"]:::logic
        charInf["character_inference.py"]:::logic
        makeInf["make_inference.py"]:::logic
        standAloneInf["standalone_character_inference.py"]:::logic
        memory["memory.py"]:::logic
        procKey["process_keywords.py"]:::logic
        utils["utils.py"]:::logic

        RulesEngine["Rules Engine"]:::logic
        applyRules["apply_rules.py"]:::logic
        ruleEval["rule_evaluator.py"]:::logic
        timerRules["timer_rules_manager.py"]:::logic
        screenEff["screen_effects.py"]:::logic
        rulesUI1["rules_manager_ui.py"]:::logic
        rulesUI2["rules_toggle_manager.py"]:::logic

        GenModules["Generation Modules"]:::logic
        genActor["generate_actor.py"]:::logic
        genSetting["generate_setting.py"]:::logic
        genSummary["generate_summary.py"]:::logic
        genRandom["generate_random_list.py"]:::logic

        ScribeAgent["Scribe Agent"]:::logic
        agentChat["agent_chat.py"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        JSONStore["JSON Data Store\n(/data/, /saves/)"]:::store
        ConfigStore["Config Store"]:::utility
    end

    ExternalLLM["LLM API"]:::external

    %% Connections
    ChatWindow -->|"user input"| CoreEngine
    EditorPanel -->|"editor actions"| CoreEngine
    PlayerPanel -->|"player actions"| CoreEngine
    SoundPlayer -->|"play sound"| SoundPlayer
    SoundPlayer -->|"loads from"| SoundPlayer
    SoundPlayer --> JSONStore
    CoreEngine -->|"apply rules"| RulesEngine
    CoreEngine -->|"call LLM"| charInf
    RulesEngine -->|"call LLM"| makeInf
    CoreEngine --> GenModules
    GenModules -->|"persist new data"| JSONStore
    ScribeAgent -->|"call LLM"| ExternalLLM
    CoreEngine -->|"persist state"| JSONStore
    CoreEngine -->|"load config"| ConfigStore

    %% Hierarchy Links
    CoreEngine --> split1
    CoreEngine --> split2
    CoreEngine --> split3
    CoreEngine --> tabMan
    CoreEngine --> uiWidgets
    CoreEngine --> applyStyle
    CoreEngine --> splash
    CoreEngine --> intro
    CoreEngine --> over
    CoreEngine --> charInf
    CoreEngine --> makeInf
    CoreEngine --> standAloneInf
    CoreEngine --> memory
    CoreEngine --> procKey
    CoreEngine --> utils

    RulesEngine --> applyRules
    RulesEngine --> ruleEval
    RulesEngine --> timerRules
    RulesEngine --> screenEff
    RulesEngine --> rulesUI1
    RulesEngine --> rulesUI2

    GenModules --> genActor
    GenModules --> genSetting
    GenModules --> genSummary
    GenModules --> genRandom

    ScribeAgent --> agentChat

    %% Click Events
    click ChatWindow "https://github.com/newbikscube/chatbotrpg/blob/main/src/chatBotRPG.py"
    click ConfigStore "https://github.com/newbikscube/chatbotrpg/blob/main/config.json"
    click SoundPlayer "https://github.com/newbikscube/chatbotrpg/blob/main/sounds/*.mp3"
    click split1 "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/top_splitter.py"
    click split2 "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/bottom_splitter.py"
    click split3 "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/themed_splitter.py"
    click tabMan "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/tab_manager.py"
    click uiWidgets "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/ui_widgets.py"
    click applyStyle "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/apply_stylesheet.py"
    click splash "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/splash_screen.py"
    click intro "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/game_intro.py"
    click over "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/game_over.py"
    click charInf "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/character_inference.py"
    click makeInf "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/make_inference.py"
    click standAloneInf "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/standalone_character_inference.py"
    click memory "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/memory.py"
    click procKey "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/process_keywords.py"
    click utils "https://github.com/newbikscube/chatbotrpg/blob/main/src/core/utils.py"
    click applyRules "https://github.com/newbikscube/chatbotrpg/blob/main/src/rules/apply_rules.py"
    click ruleEval "https://github.com/newbikscube/chatbotrpg/blob/main/src/rules/rule_evaluator.py"
    click timerRules "https://github.com/newbikscube/chatbotrpg/blob/main/src/rules/timer_rules_manager.py"
    click screenEff "https://github.com/newbikscube/chatbotrpg/blob/main/src/rules/screen_effects.py"
    click rulesUI1 "https://github.com/newbikscube/chatbotrpg/blob/main/src/rules/rules_manager_ui.py"
    click rulesUI2 "https://github.com/newbikscube/chatbotrpg/blob/main/src/rules/rules_toggle_manager.py"
    click genActor "https://github.com/newbikscube/chatbotrpg/blob/main/src/generate/generate_actor.py"
    click genSetting "https://github.com/newbikscube/chatbotrpg/blob/main/src/generate/generate_setting.py"
    click genSummary "https://github.com/newbikscube/chatbotrpg/blob/main/src/generate/generate_summary.py"
    click genRandom "https://github.com/newbikscube/chatbotrpg/blob/main/src/generate/generate_random_list.py"
    click agentChat "https://github.com/newbikscube/chatbotrpg/blob/main/src/scribe/agent_chat.py"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef store fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef utility fill:#FFFACD,stroke:#333,stroke-width:1px
```
