# ksanadock/microverse architecture

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

- Interactive diagram: https://gitdiagram.com/ksanadock/microverse
- Repository: https://github.com/ksanadock/microverse

## Overview

##### Project type and purpose
- Purpose: simulate a micro-world of AI agents with independent memory, dialogue, tasks, and environment awareness.

##### File structure
- Top-level directories:
- asset/ (graphics, fonts, shaders, themes)
- scene/ (Godot .tscn scenes: characters, maps, UI prefabs)
- script/ (GDScript controllers):
– ai/ (AIAgent, APIManager, DialogManager, MemoryManager, ConversationManager, background_story, memory)
– ui/ (UI widgets: menus, labels, save/load, settings)
– root‐level scripts (CharacterController, TaskManager, RoomManager, GameSaveManager, CameraController, etc.)
- Config: project.godot, .gitignore, README, LICENSE.
- Storage: JSON-based local storage via GameSaveManager & MemoryManager.
- External integration: REST API calls to multiple AI service providers.

##### Key insights from README
- Core subsystems:
- APIManager – dispatches calls to LLM providers.
- DialogManager – orchestrates natural-language exchanges.
- MemoryManager – persists AI agents’ memories.
- CharacterManager – tracks agent states, personalities, interactions.
- TaskManager – generates and monitors agent tasks.
- Scenes: maps (Office.tscn), character prefabs, UI overlays.
- UI: settings, dialog bubbles, command console, save/load, AI model selector.

##### Elements
- Labels: exact component names (e.g., “MemoryManager”, “DialogManager”, “APIManager”).
- Blue for core engine & scenes
- Green for Manager subsystems
- Orange for UI components
- Gray for assets & storage
- Purple for external services
- Rectangles for modules
- Clouds for external services

##### Final recommendations
- Be as granular as possible: treat each manager as its own node.
- Both static structure (components) and dynamic flows (runtime interactions).
- Iterate with the engineering team to validate accuracy against actual Godot scene tree and script dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        BGUI["BackgroundStoryUI"]:::ui
        CHUI["ChatHistory"]:::ui
        AIML["AIModelLabel"]:::ui
        DBUB["DialogBubble"]:::ui
        SLUI["SaveLoadUI"]:::ui
        SLUIM["SaveLoadUIManager"]:::ui
        GSUI["GlobalSettingsUI"]:::ui
        SUI["SettingsUI"]:::ui
        GDU["GodUI"]:::ui
        MMUI["MainMenu"]:::ui
        MSUI["MapSelection"]:::ui
        CUI["CommandUI"]:::ui
    end

    %% Core Engine & Scene Graph
    subgraph "Godot Engine Core" 
        direction TB
        SceneGraph["Scene & Node Graph"]:::engine
    end

    %% Subsystems / Managers
    subgraph "Subsystem Managers"
        direction TB
        APIConf["APIConfig"]:::manager
        APIMan["APIManager"]:::manager
        DialogMgr["DialogManager"]:::manager
        ConvMgr["ConversationManager"]:::manager
        DialogSvc["DialogService"]:::manager
        MemMgr["MemoryManager"]:::manager
        BSMgr["BackgroundStoryManager"]:::manager
        CharMgr["CharacterManager"]:::manager
        CharCtrl["CharacterController"]:::manager
        TaskMgr["TaskManager"]:::manager
        RoomMgr["RoomManager"]:::manager
        SPMgr["ScenePerceptionManager"]:::manager
        SaveMgr["GameSaveManager"]:::manager
        CamCtrl["CameraController"]:::manager
    end

    %% Asset Layer
    subgraph "Asset Layer"
        direction TB
        Assets["asset/ (textures, fonts, shaders, themes)"]:::storage
    end

    %% Data Persistence
    Storage["Local JSON Storage"]:::storage

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        OpenAI["OpenAI"]:::external
        Claude["Claude"]:::external
        Gemini["Gemini"]:::external
    end

    %% UI → Managers
    BGUI -->|interacts with| BSMgr
    CHUI -->|displays chat| DialogMgr
    AIML -->|shows model| APIConf
    DBUB -->|renders dialogue| DialogMgr
    SLUI -->|trigger save/load| SaveMgr
    SLUIM -->|manages UI| SaveMgr
    GSUI -->|adjust settings| APIConf
    SUI -->|configures| APIConf
    GDU -->|debug console| ConvMgr
    MMUI -->|navigation| RoomMgr
    MSUI -->|select map| RoomMgr
    CUI -->|commands| ConvMgr

    %% Managers → Engine / Scene
    CharMgr -->|spawn/move| SceneGraph
    CharCtrl -->|controls nodes| SceneGraph
    TaskMgr -->|assign tasks| CharMgr
    SPMgr -->|perceive env| RoomMgr
    RoomMgr -->|manage rooms| SceneGraph
    SaveMgr -->|save state| SceneGraph
    SaveMgr -->|load state| SceneGraph
    CamCtrl -->|camera updates| SceneGraph

    %% Dialog Flow
    DialogMgr -->|orchestrates| APIMan
    APIMan -->|calls| OpenAI
    APIMan -->|calls| Claude
    APIMan -->|calls| Gemini
    OpenAI -->|response| DialogMgr
    Claude -->|response| DialogMgr
    Gemini -->|response| DialogMgr
    DialogSvc -->|helper| APIMan

    %% Memory Persistence
    MemMgr -->|write/read| Storage
    Storage -->|persist data| MemMgr

    %% GameSave ↔ Managers
    SaveMgr -->|saves| APIMan
    SaveMgr -->|saves| DialogMgr
    SaveMgr -->|saves| MemMgr
    SaveMgr -->|saves| CharMgr
    SaveMgr -->|saves| TaskMgr
    SaveMgr -->|saves| RoomMgr
    SaveMgr -->|saves| SPMgr

    %% Color Legend styling
    classDef ui fill:#f9d5bb,stroke:#d17e3e,color:#000;
    classDef engine fill:#bbdef0,stroke:#2196f3,color:#000;
    classDef manager fill:#c8e6c9,stroke:#2e7d32,color:#000;
    classDef storage fill:#e0e0e0,stroke:#9e9e9e,color:#000;
    classDef external fill:#e1bee7,stroke:#8e24aa,color:#000;

    %% Click Events
    click APIMan "https://github.com/ksanadock/microverse/blob/main/script/ai/APIManager.gd"
    click APIConf "https://github.com/ksanadock/microverse/blob/main/script/ai/APIConfig.gd"
    click DialogMgr "https://github.com/ksanadock/microverse/blob/main/script/ai/DialogManager.gd"
    click ConvMgr "https://github.com/ksanadock/microverse/blob/main/script/ai/ConversationManager.gd"
    click DialogSvc "https://github.com/ksanadock/microverse/blob/main/script/ai/DialogService.gd"
    click MemMgr "https://github.com/ksanadock/microverse/blob/main/script/ai/memory/MemoryManager.gd"
    click BSMgr "https://github.com/ksanadock/microverse/blob/main/script/ai/background_story/BackgroundStoryManager.gd"
    click BGUI "https://github.com/ksanadock/microverse/blob/main/script/ai/background_story/BackgroundStoryUI.gd"
    click CharMgr "https://github.com/ksanadock/microverse/blob/main/script/CharacterManager.gd"
    click CharCtrl "https://github.com/ksanadock/microverse/blob/main/script/CharacterController.gd"
    click TaskMgr "https://github.com/ksanadock/microverse/blob/main/script/TaskManager.gd.uid"
    click RoomMgr "https://github.com/ksanadock/microverse/blob/main/script/RoomManager.gd"
    click SPMgr "https://github.com/ksanadock/microverse/blob/main/script/ScenePerceptionManager.gd.uid"
    click SaveMgr "https://github.com/ksanadock/microverse/blob/main/script/GameSaveManager.gd"
    click CamCtrl "https://github.com/ksanadock/microverse/blob/main/script/CameraController.gd"
    click CHUI "https://github.com/ksanadock/microverse/blob/main/script/ChatHistory.gd"
    click CHUI "https://github.com/ksanadock/microverse/blob/main/scene/ChatHistory.tscn"
    click AIML "https://github.com/ksanadock/microverse/blob/main/script/ui/AIModelLabel.gd"
    click AIML "https://github.com/ksanadock/microverse/blob/main/scene/ui/AIModelLabel.tscn"
    click DBUB "https://github.com/ksanadock/microverse/blob/main/script/ui/DialogBubble.gd"
    click DBUB "https://github.com/ksanadock/microverse/blob/main/scene/ui/DialogBubble.tscn"
    click SLUI "https://github.com/ksanadock/microverse/blob/main/script/ui/SaveLoadUI.gd"
    click SLUI "https://github.com/ksanadock/microverse/blob/main/scene/ui/SaveLoadUI.tscn"
    click SLUIM "https://github.com/ksanadock/microverse/blob/main/script/ui/SaveLoadUIManager.gd"
    click SLUIM "https://github.com/ksanadock/microverse/blob/main/scene/ui/SaveLoadUIManager.tscn"
    click GSUI "https://github.com/ksanadock/microverse/blob/main/script/ui/GlobalSettingsUI.gd"
    click GSUI "https://github.com/ksanadock/microverse/blob/main/scene/ui/GlobalSettingsUI.tscn"
    click SUI "https://github.com/ksanadock/microverse/blob/main/script/ui/SettingsUI.gd.uid"
    click GDU "https://github.com/ksanadock/microverse/blob/main/script/ui/GodUI.gd"
    click GDU "https://github.com/ksanadock/microverse/blob/main/scene/ui/GodUI.tscn"
    click MMUI "https://github.com/ksanadock/microverse/blob/main/script/ui/MainMenu.gd"
    click MSUI "https://github.com/ksanadock/microverse/blob/main/script/ui/MapSelection.gd"
    click CUI "https://github.com/ksanadock/microverse/blob/main/scene/ui/CommandUI.tscn"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/fonts/"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/shaders/"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/theme/"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/ui/"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/characters/"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/maps/"
    click Assets "https://github.com/ksanadock/microverse/tree/main/asset/"
```
