# gubaiovo/mcdr_chat_with_ai architecture

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

- Interactive diagram: https://gitdiagram.com/gubaiovo/mcdr_chat_with_ai
- Repository: https://github.com/gubaiovo/mcdr_chat_with_ai

## Overview

##### Project type and purpose
- This is an MCDReforged (“MCDR”) plugin written in Python. Its purpose is to connect a running Minecraft server to OpenAI-compatible models, allowing players to chat with an AI “villager” or NPC via in-game chat commands.

##### File structure
- Top-level files:
- LICENSE, README.md / README_CN.md
- mcdreforged.plugin.json – plugin manifest that MCDR uses to load the plugin
- requirements.txt – lists Python dependencies (e.g., openai)
- chat_with_ai/ directory (the plugin package):
- __init__.py – entry point, command registration with MCDR
- ConfigManager.py – loads and watches config/config.json
- DataManager.py – manages chat history, context per player
- config/ directory:
- config.json – plugin settings (API key, model, system prompt defaults)
- lang/ directory:
- en_us.yml, zh_cn.yml – localization strings for in-game messages
- doc/ directory: usage documentation

##### Key insights from README
- Uses the openai Python library to communicate with OpenAI API
- Supports commands like !!dsp msg, !!dsp history, !!dsp clear, etc.
- Fully config-driven: language packs, system and prefix presets, history persistence

##### Main components & interactions
a. Components
1. Minecraft Server + MCDReforged plugin host
2. chat_with_ai plugin
– Command Handler (registered via __init__.py)
– ConfigManager (reads config.json, reloads on change)
– DataManager (stores per-player conversation context)
– LangService (loads YAML language files)
3. OpenAI API (external HTTP service)
4. Local storage (file system for config.json, history in memory or disk)
b. Interactions / Data Flow
1. Player types “!!dsp msg Hello” in chat →
2. MCDReforged routes command to chat_with_ai.Command Handler →
3. Command Handler uses ConfigManager & LangService to build request context →
4. DataManager appends user message to conversation history →
5. Plugin calls OpenAI API with full message history →
6. OpenAI responds with AI message →
7. DataManager stores AI response →
8. Plugin sends response back to player via server chat
c. Architectural patterns
- Plugin / Extension pattern (MCDReforged host + plugin module)
- Manager pattern (ConfigManager, DataManager, LangService)
- Command pattern (each “!!dsp” command maps to a handler method)
d. Technologies & frameworks
- Python 3.x
- MCDReforged plugin API
- openai Python SDK
- YAML for localization
- JSON for configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% In-game / Server
    Player["Player"]:::server
    Server["Minecraft Server\n+ MCDReforged"]:::server
    PluginManifest["mcdreforged.plugin.json"]:::server

    Player -->|sends “!!dsp msg”| Server
    Server -->|routes command| CommandHandler

    %% Plugin Internal Components
    subgraph "chat_with_ai Plugin" 
        direction TB
        CommandHandler["Command Handler\n(__init__.py)"]:::plugin
        ConfigManager["ConfigManager\n(ConfigManager.py)"]:::plugin
        DataManager["DataManager\n(DataManager.py)"]:::plugin
        LangService["LangService\n(en_us.yml, zh_cn.yml)"]:::plugin
    end

    %% External Service
    OpenAI["OpenAI API\n(external HTTP)"]:::external

    %% File System
    subgraph "File System" 
        direction TB
        ConfigFile["config.json"]:::fs
        HistoryStore["History Store\n(in-memory/disk)"]:::fs
        Lang_en["en_us.yml"]:::fs
        Lang_zh["zh_cn.yml"]:::fs
    end

    %% Main Flow
    Server -->|calls handler| CommandHandler
    CommandHandler -->|load config| ConfigManager
    ConfigManager -->|reads| ConfigFile
    CommandHandler -->|load localization| LangService
    LangService -->|reads| Lang_en
    LangService -->|reads| Lang_zh
    CommandHandler -->|append message| DataManager
    DataManager -->|writes| HistoryStore
    CommandHandler -->|HTTP request| OpenAI
    OpenAI -->|HTTP response| CommandHandler
    CommandHandler -->|send chat response| Server
    Server -->|message to| Player

    %% Background / Watchers
    ConfigFile -.->|watch file| ConfigManager
    HistoryStore -.->|persist context| DataManager

    %% Click Events
    click PluginManifest "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/mcdreforged.plugin.json"
    click CommandHandler "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/chat_with_ai/__init__.py"
    click ConfigManager "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/chat_with_ai/ConfigManager.py"
    click DataManager "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/chat_with_ai/DataManager.py"
    click Lang_en "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/lang/en_us.yml"
    click Lang_zh "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/lang/zh_cn.yml"
    click ConfigFile "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/config/config.json"
    click Requirements "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/requirements.txt"
    click README1 "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/doc/README.md"
    click README2 "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/chat_with_ai/doc/README_CN.md"
    click ProjectReadme "https://github.com/gubaiovo/mcdr_chat_with_ai/blob/main/README.md"
    click License "https://github.com/gubaiovo/mcdr_chat_with_ai/tree/main/LICENSE"

    %% Styles
    classDef server fill:#b7eb8f,stroke:#4caf50,color:#000;
    classDef plugin fill:#90caf9,stroke:#1e88e5,color:#000;
    classDef external fill:#ffcc80,stroke:#fb8c00,color:#000;
    classDef fs fill:#eeeeee,stroke:#9e9e9e,color:#000;
```
