# luddang/minecollector architecture

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

- Interactive diagram: https://gitdiagram.com/luddang/minecollector
- Repository: https://github.com/luddang/minecollector

## Overview

##### Project type and purpose
- This is a Minecraft server plugin (“MineCollector”) written in Java (with a small Kotlin micro-service) that tracks and scores item collections, advancements, and exposes commands/GUI to players.
- Its goal is to run inside a Bukkit/Spigot server, listen to in-game events, persist player data, offer commands (collect, book, check, ranking, guide), auto-save data, and optionally sync across servers via a separate Kotlin SyncServer.

##### File structure
- Top-level build files (build.gradle, settings.gradle, gradlew) configure a Gradle-based Java project with a Kotlin submodule.
- src/main/java/com/doubledeltas/minecollector: core plugin code
- MineCollector.java – plugin entry point
- GameDirector.java – central orchestrator
- config/… – ConfigManager, McolConfig (reads config.yml)
- data/… – DataManager, GameData, ExtendedGameData, DataAutoSaver
- command/… – CommandRoot, CommandNode, concrete commands (BookCommand, CollectCommand, etc.)
- listener/… – EventManager, various Bukkit event listeners
- gui/… – GUI screens using Bukkit inventories
- item/… – ItemManager, ItemBuilder, item-code abstractions
- util/… – helper classes (Yamls, MessageUtil, etc.)
- src/main/kotlin/live/luya/minecollector: external sync server (MineCollectorSyncServer.kt)
- src/main/resources: config.yml, plugin.yml, item definitions

##### README insights
- Describes scoring rules, commands, auto-save every 10 minutes, configurable via config.yml, and a hook for dropping ender eggs.

a. Main components:
1. Bukkit/Spigot Server (platform)
2. Plugin Loader & Lifecycle (calls onEnable/onDisable in MineCollector.java)
3. GameDirector (plugin core)
4. ConfigManager (loads config.yml → McolConfig, chapters)
5. EventManager & Listeners (player events, entity deaths, advancements)
6. CommandRoot & CommandNodes (parses and dispatches commands)
7. DataManager & DataAutoSaver (holds per-player GameData, flushes to YAML)
8. GUI Module (HubGui, CollectionGui, DumpGui)
9. Item Module (ItemManager, ItemBuilder, itemCode strategy)
10. Utility Layer (Yamls, MessageUtil, SoundUtil)
11. External Sync Server (MineCollectorSyncServer – optional network sync)
12. Persistence Storage (flat YAML files in plugin folder)

b. Relationships & interactions:
- On plugin enable → GameDirector initializes ConfigManager, DataManager, registers EventManager, registers command handlers (CommandRoot).
- Bukkit events → forwarded to EventManager → individual Listeners → update GameData via DataManager → may fire TotalScoreModifiedEvent.
- Player issues a command → Bukkit hands off to CommandRoot → selects Concrete CommandNode → executes logic (reads/writes GameData, sends messages, opens GUI).
- GUI opens an Inventory screen → player clicks → GUI module handles click events via registered listeners.
- DataAutoSaver scheduled task every N minutes → invokes DataManager.saveAll() → writes YAML files to disk via Yamls util.
- (Optional) For cross-server sync → plugin TCP/HTTP client communicates with MineCollectorSyncServer → exchanges serialized data via GsonDateConverter.

c. Architectural patterns & principles:
- Event-Driven (Bukkit events → custom events → listeners)
- Command Pattern (CommandRoot/CommandNode hierarchy)
- Singleton/Manager classes for cross-cutting services (ConfigManager, DataManager, EventManager)
- Layered separation: Core → Commands/Listeners → Managers → Persistence → Resources
- Strategy pattern in itemCode (GuiItem, StaticItem)

d. Key technologies & frameworks:
- Java 17, Bukkit/Spigot API
- Gradle build, Kotlin + kotlinx for SyncServer
- SnakeYAML (via Yamls utility) for config/data
- GsonDateConverter for JSON date handling
- Bukkit scheduler for auto-save

##### Final advice
- Be exhaustive: include all subsystems (Config, Command, Event, Data, GUI, Item, Util, Sync).
- Clearly demarcate boundaries: Plugin vs. Host Server vs. External Sync Service vs. File System.
- Data flows (player actions → plugin → storage → back to player).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Environment
    BukkitServer(["Minecraft (Bukkit/Spigot) Server"]):::external

    %% Plugin Boundary
    subgraph "MineCollector Plugin"
        direction TB
        PluginLoader["MineCollector.java"]:::core
        GameDirector["GameDirector.java"]:::core

        subgraph "Configuration (yellow)"
            direction TB
            ConfigManager["ConfigManager.java"]:::config
            McolConfig["McolConfig.java"]:::config
            ConfigChapters["Config Chapters"]:::config
        end

        subgraph "Event System (blue)"
            direction TB
            EventManager["EventManager.java"]:::core
            Listeners["Listeners"]:::core
        end

        subgraph "Command Framework (blue)"
            direction TB
            CommandRoot["CommandRoot.java"]:::core
            CommandNode["CommandNode.java"]:::core
            ConcreteCommands["Concrete Commands"]:::core
        end

        subgraph "Data & Persistence (green)"
            direction TB
            DataManager["DataManager.java"]:::data
            DataAutoSaver["DataAutoSaver.java"]:::data
            DataModels["GameData, ExtendedGameData, GameStatistics"]:::data
            DiskStorage[("YAML Storage<br/>(config.yml, item/*.yml, plugin.yml)")]:::storage
        end

        subgraph "GUI Module (blue)"
            direction TB
            GuiBase["Gui.java"]:::core
            HubGui["HubGui.java"]:::core
            CollectionGui["CollectionGui.java"]:::core
            DumpGui["DumpGui.java"]:::core
        end

        subgraph "Item Module (blue)"
            direction TB
            ItemManager["ItemManager.java"]:::core
            ItemBuilder["ItemBuilder.java"]:::core
            ItemCode["ItemCode Strategies"]:::core
            ItemManagersInline["Embedded Managers"]:::core
        end

        subgraph "Utility Layer (grey)"
            direction TB
            UtilClasses["util/*.java"]:::util
        end
    end

    %% External Service
    MineCollectorSyncServer["MineCollectorSyncServer.kt"]:::external
    GsonDateConverter["GsonDateConverter.kt"]:::external

    %% Connections
    BukkitServer -->|loads| PluginLoader
    PluginLoader --> GameDirector
    GameDirector --> ConfigManager
    GameDirector --> DataManager
    GameDirector --> EventManager
    GameDirector --> CommandRoot

    ConfigManager --> McolConfig
    ConfigManager --> ConfigChapters
    DataManager --> DataModels
    DataAutoSaver --> DataManager
    DataAutoSaver -->|writes| DiskStorage
    DataManager -->|loads/saves| DiskStorage

    EventManager --> Listeners
    Listeners --> DataManager
    CommandRoot --> CommandNode
    CommandNode --> ConcreteCommands
    ConcreteCommands --> DataManager
    ConcreteCommands --> GuiBase

    GuiBase --> HubGui
    GuiBase --> CollectionGui
    GuiBase --> DumpGui

    ItemManager --> ItemBuilder
    ItemManager --> ItemCode
    ItemManager --> ItemManagersInline

    CommandNode -->|uses| UtilClasses
    EventManager -->|uses| UtilClasses

    PluginLoader -->|schedules| DataAutoSaver

    PluginLoader -.->|optional sync| MineCollectorSyncServer
    MineCollectorSyncServer -->|uses| GsonDateConverter
    GameDirector -.-> MineCollectorSyncServer

    %% Click Events
    click PluginLoader "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/MineCollector.java"
    click GameDirector "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/GameDirector.java"
    click ConfigManager "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/config/ConfigManager.java"
    click McolConfig "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/config/McolConfig.java"
    click ConfigChapters "https://github.com/luddang/minecollector/tree/main/src/main/java/com/doubledeltas/minecollector/config/chapter/"
    click EventManager "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/listener/EventManager.java"
    click Listeners "https://github.com/luddang/minecollector/tree/main/src/main/java/com/doubledeltas/minecollector/listener/"
    click CommandRoot "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/command/CommandRoot.java"
    click CommandNode "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/command/CommandNode.java"
    click ConcreteCommands "https://github.com/luddang/minecollector/tree/main/src/main/java/com/doubledeltas/minecollector/command/impl/"
    click DataManager "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/data/DataManager.java"
    click DataAutoSaver "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/data/DataAutoSaver.java"
    click DataModels "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/data/GameData.java"
    click GuiBase "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/gui/Gui.java"
    click HubGui "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/gui/HubGui.java"
    click CollectionGui "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/gui/CollectionGui.java"
    click DumpGui "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/gui/DumpGui.java"
    click ItemManager "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/item/ItemManager.java"
    click ItemBuilder "https://github.com/luddang/minecollector/blob/main/src/main/java/com/doubledeltas/minecollector/item/ItemBuilder.java"
    click ItemCode "https://github.com/luddang/minecollector/tree/main/src/main/java/com/doubledeltas/minecollector/item/itemCode/"
    click ItemManagersInline "https://github.com/luddang/minecollector/tree/main/src/main/java/com/doubledeltas/minecollector/item/manager/"
    click UtilClasses "https://github.com/luddang/minecollector/tree/main/src/main/java/com/doubledeltas/minecollector/util/"
    click MineCollectorSyncServer "https://github.com/luddang/minecollector/blob/main/src/main/kotlin/live/luya/minecollector/MineCollectorSyncServer.kt"
    click GsonDateConverter "https://github.com/luddang/minecollector/blob/main/src/main/kotlin/live/luya/minecollector/serialization/GsonDateConverter.kt"

    %% Styles
    classDef core fill:#D0E1FF,stroke:#0366D6,color:#0366D6;
    classDef data fill:#DFF5D0,stroke:#3C763D,color:#3C763D;
    classDef external fill:#FFE5D0,stroke:#D9730D,color:#D9730D;
    classDef config fill:#FFF8CC,stroke:#D6A700,color:#D6A700;
    classDef storage fill:#E0FFE0,stroke:#2E7D32,color:#2E7D32;
    classDef util fill:#F0F0F0,stroke:#888888,color:#555555;
```
