# koirdsuzu/uberitems architecture

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

- Interactive diagram: https://gitdiagram.com/koirdsuzu/uberitems
- Repository: https://github.com/koirdsuzu/uberitems

## Overview

##### Project type and purpose
- This is a Minecraft “Paper” server plugin named UberItems.
- Purpose: provide a GUI-based item shop with distance-based shipping, integrating with Vault for economy and optionally QuickShop for player shops.

- Minecraft Server → UberItems Plugin Core (lifecycle hooks, events)
- Plugin Core → Configuration Layer (load/save)
- Plugin Core → Command Layer & Event Layer (register)
- Command Layer → GUI Layer (open main menu)
- Event Layer → GUI Layer (handle clicks → navigate GUIs)
- GUI Layer ↔ Model Layer (GUI displays CategoryItem/ShopItem data)
- GUI Layer → Persistence Layer (read/write player shop data)
- GUI Layer → Economy Layer (calculate shipping + price)
- Economy Layer → Vault API (external service)
- GUI Layer → Integration Layer (when accessing player shops via QuickShop)
- Integration Layer ↔ QuickShop API (external plugin)
- Utility Layer – used by GUI Layer, Model Layer, Integration Layer for common tasks

##### Architectural patterns & design principles
- Modular package‐based separation (commands, listeners, gui, model, util, config, database, economy, integration)
- Event-driven design (listeners respond to server & GUI events)
- MVC-inspired layering in GUI: Model stores data, View = GUIs, Controller = listeners/commands
- Dependency Injection via ConfigManager, VaultManager, PlayerDatabase

##### Essential elements
- Main plugin component with lifecycle
- Layers: Config, Commands, Listeners, GUI, Model, Persistence, Economy, Integration, Utils
- External services (Vault API, QuickShop API)

## Diagram (Mermaid)

```mermaid
graph TD
    %% External
    MS["Minecraft Server (Paper API)"]:::ext

    %% Plugin Core
    subgraph "Plugin Core"
        UI["UberItems"]:::core
        PY["plugin.yml"]:::core
    end

    MS -->|"lifecycle, events"| UI
    UI -->|"register commands & listeners"| CMD_LAYER
    UI -->|"load configs"| CONFIG_LAYER

    %% Configuration Layer
    subgraph "Configuration Layer"
        CONFIG_LAYER["ConfigManager"]:::config
        AY["adminshop.yml"]:::config
        CY["config.yml"]:::config
    end

    UI -->|"load/save"| CONFIG_LAYER

    %% Command Layer
    subgraph "Command Layer"
        CMD_LAYER["UberMenuCommand"]:::cmd
    end
    CMD_LAYER -->|"open GUI"| GUI_LAYER

    %% Event / Listener Layer
    subgraph "Event/Listener Layer"
        EL1["GUIListener"]:::listener
        EL2["PlayerListener"]:::listener
    end
    UI -->|"register"| EL1
    UI -->|"register"| EL2
    EL1 -->|"handle clicks"| GUI_LAYER
    EL2 -->|"handle player events"| GUI_LAYER

    %% GUI Layer
    subgraph "GUI Layer"
        GUI_LAYER["AbstractGUI"]:::gui
        GM["UberMenuGUI"]:::gui
        GA["AdminShopGUI"]:::gui
        GS["ShopListGUI"]:::gui
        GP["PlayerShopGUI"]:::gui
        GMY["MyShopGUI"]:::gui
        GC["ItemCategoryGUI"]:::gui
        GPL["PlayerListGUI"]:::gui
    end
    GUI_LAYER -->|extends| GM
    GUI_LAYER -->|extends| GA
    GUI_LAYER -->|extends| GS
    GUI_LAYER -->|extends| GP
    GUI_LAYER -->|extends| GMY
    GUI_LAYER -->|extends| GC
    GUI_LAYER -->|extends| GPL

    %% Model Layer
    subgraph "Model Layer"
        MI["CategoryItem"]:::model
        MSI["ShopItem"]:::model
        SE["ShopEntry"]:::model
    end
    GUI_LAYER -->|"uses data"| MI
    GUI_LAYER -->|"uses data"| MSI
    GUI_LAYER -->|"uses data"| SE

    %% Persistence Layer
    subgraph "Persistence Layer"
        DB["PlayerDatabase"]:::db
    end
    GUI_LAYER -->|"read/write"| DB

    %% Economy Layer
    subgraph "Economy Layer"
        VM["VaultManager"]:::econ
    end
    GUI_LAYER -->|"calculate price/shipping"| VM
    VM -->|"calls"| VACLOUD

    %% Integration Layer
    subgraph "Integration Layer"
        QI["QuickShopIntegration"]:::integration
    end
    GUI_LAYER -->|"access player shops"| QI
    QI -->|"adapts"| QSCLOUD

    %% Utility Layer
    subgraph "Utility Layer"
        U1["BottomRowUtil"]:::util
        U2["ChatUtil"]:::util
        U3["ItemReference"]:::util
        U4["LocationUtil"]:::util
        U5["PaginationUtil"]:::util
    end
    GUI_LAYER -->|"uses"| U1
    GUI_LAYER -->|"uses"| U2
    GUI_LAYER -->|"uses"| U3
    GUI_LAYER -->|"uses"| U4
    GUI_LAYER -->|"uses"| U5
    MI --->|"uses"| U3
    QI --->|"uses"| U4
    QI --->|"uses"| U5

    %% External services
    VACLOUD["Vault API"]:::ext
    QSCLOUD["QuickShop API"]:::ext

    %% Click Events
    click UI "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/UberItems.java"
    click PY "https://github.com/koirdsuzu/uberitems/blob/main/src/main/resources/plugin.yml"
    click CONFIG_LAYER "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/config/ConfigManager.java"
    click AY "https://github.com/koirdsuzu/uberitems/blob/main/src/main/resources/adminshop.yml"
    click CY "https://github.com/koirdsuzu/uberitems/blob/main/src/main/resources/config.yml"
    click CMD_LAYER "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/commands/UberMenuCommand.java"
    click EL1 "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/listeners/GUIListener.java"
    click EL2 "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/listeners/PlayerListener.java"
    click GUI_LAYER "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/AbstractGUI.java"
    click GM "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/UberMenuGUI.java"
    click GA "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/AdminShopGUI.java"
    click GS "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/ShopListGUI.java"
    click GP "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/PlayerShopGUI.java"
    click GMY "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/MyShopGUI.java"
    click GC "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/ItemCategoryGUI.java"
    click GPL "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/gui/PlayerListGUI.java"
    click MI "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/model/CategoryItem.java"
    click MSI "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/model/ShopItem.java"
    click SE "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/model/ShopEntry.java"
    click DB "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/database/PlayerDatabase.java"
    click VM "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/economy/VaultManager.java"
    click QI "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/integration/QuickShopIntegration.java"
    click U1 "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/util/BottomRowUtil.java"
    click U2 "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/util/ChatUtil.java"
    click U3 "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/util/ItemReference.java"
    click U4 "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/util/LocationUtil.java"
    click U5 "https://github.com/koirdsuzu/uberitems/blob/main/src/main/java/com/koirdsuzu/uberitems/util/PaginationUtil.java"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef ext fill:#f0e6ff,stroke:#4b0082,color:#4b0082
    classDef config fill:#ccffe6,stroke:#006644,color:#006644
    classDef cmd fill:#ffdede,stroke:#b30000,color:#b30000
    classDef listener fill:#fff0b3,stroke:#ff8c00,color:#ff8c00
    classDef gui fill:#ffe5cc,stroke:#cc6600,color:#cc5200
    classDef model fill:#ccffcc,stroke:#006600,color:#006600
    classDef db fill:#ccffcc,stroke:#006600,color:#006600
    classDef econ fill:#e6ccff,stroke:#800080,color:#800080
    classDef integration fill:#e6ccff,stroke:#800080,color:#800080
    classDef util fill:#e0e0e0,stroke:#404040,color:#404040
```
