# neutralplasma/magicbees architecture

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

- Interactive diagram: https://gitdiagram.com/neutralplasma/magicbees
- Repository: https://github.com/neutralplasma/magicbees

## Overview

MagicBees is a Minecraft server plugin for configurable, upgradeable beehives. Players interact with hives to harvest honey or comb and upgrade production; the plugin exposes controller APIs for hive operations, requirements, rewards, providers, and translations. Hive state is cached by chunk and persisted through a DAO, while menus and event listeners provide player-facing interaction. The README is only a title, so capability details come from the API and sampled source; unsampled command and integration wiring is shown only where plugin registration is evidenced.

Main entry points: [`core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt`](https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt) (Hive operations), [`plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt`](https://github.com/neutralplasma/magicbees/blob/main/plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt) (Plugin lifecycle), [`gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/guis/BeeHiveMenu.kt`](https://github.com/neutralplasma/magicbees/blob/main/gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/guis/BeeHiveMenu.kt) (Hive menu), [`api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/BeeHiveController.kt`](https://github.com/neutralplasma/magicbees/blob/main/api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/BeeHiveController.kt) (Hive operations API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Plugin entry"]
  node_plugin["Plugin lifecycle<br/>[MagicBeesPlugin.kt]"]
  node_listeners["World listeners"]
  node_commands["Plugin commands"]
end

subgraph group_hives["Hive gameplay"]
  node_hive_api["Hive operations API"]
  node_hive_model["Hive state model<br/>[BeeHive.kt]"]
  node_hive_logic["Hive operations"]
end

subgraph group_services["API services"]
  node_requirements["Requirement parsing"]
  node_rewards["Reward parsing"]
  node_providers["Provider integrations"]
  node_translations["Translations service"]
end

subgraph group_persistence["Hive persistence"]
  node_storage_setup["Storage setup"]
  node_chunk_cache["Chunk hive cache"]
  node_dao["Hive DAO<br/>[BeeHiveDao.kt]"]
  node_hive_store[("Hive database<br/>[BeeHiveMysql.kt]")]
end

subgraph group_ui["Player interaction"]
  node_gui["GUI controller<br/>[GuiController.kt]"]
  node_hive_menu["Hive menu<br/>[BeeHiveMenu.kt]"]
end

node_player(("Player"))
node_server(("Minecraft server"))

node_plugin -->|"initializes"| node_storage_setup
node_plugin -->|"initializes"| node_gui
node_plugin -->|"registers"| node_listeners
node_plugin -->|"registers"| node_commands
node_player -.->|"interacts"| node_listeners
node_player -.->|"invokes"| node_commands
node_listeners -.->|"uses"| node_hive_api
node_commands -.->|"uses"| node_hive_api
node_hive_logic -->|"implements"| node_hive_api
node_hive_logic -->|"updates"| node_hive_model
node_hive_logic -->|"delegates storage"| node_chunk_cache
node_hive_logic -.->|"evaluates"| node_requirements
node_hive_logic -.->|"applies"| node_rewards
node_storage_setup -->|"creates"| node_chunk_cache
node_storage_setup -->|"initializes"| node_dao
node_chunk_cache -->|"reads writes"| node_dao
node_dao -.->|"implemented by"| node_hive_store
node_gui -.->|"manages"| node_hive_menu
node_hive_menu -->|"requests hive data"| node_hive_api
node_hive_menu -->|"requests text"| node_translations
node_player -.->|"uses"| node_hive_menu
node_server -.->|"hosts"| node_plugin

click node_plugin "https://github.com/neutralplasma/magicbees/blob/main/plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt"
click node_listeners "https://github.com/neutralplasma/magicbees/tree/main/plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/listeners"
click node_commands "https://github.com/neutralplasma/magicbees/tree/main/plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/commands"
click node_hive_api "https://github.com/neutralplasma/magicbees/blob/main/api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/BeeHiveController.kt"
click node_hive_model "https://github.com/neutralplasma/magicbees/blob/main/api/src/main/kotlin/eu/virtusdevelops/magicbees/api/models/BeeHive.kt"
click node_hive_logic "https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt"
click node_requirements "https://github.com/neutralplasma/magicbees/tree/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/requirements"
click node_rewards "https://github.com/neutralplasma/magicbees/tree/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/rewards"
click node_providers "https://github.com/neutralplasma/magicbees/tree/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/providers"
click node_translations "https://github.com/neutralplasma/magicbees/blob/main/api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/TranslationsController.kt"
click node_storage_setup "https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/StorageController.kt"
click node_chunk_cache "https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveStorageController.kt"
click node_dao "https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/storage/BeeHiveDao.kt"
click node_hive_store "https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/storage/mysql/BeeHiveMysql.kt"
click node_gui "https://github.com/neutralplasma/magicbees/blob/main/gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/GuiController.kt"
click node_hive_menu "https://github.com/neutralplasma/magicbees/blob/main/gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/guis/BeeHiveMenu.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_listeners,node_commands toneBlue
class node_hive_api,node_hive_model,node_hive_logic toneAmber
class node_requirements,node_rewards,node_providers,node_translations,node_server toneMint
class node_storage_setup,node_chunk_cache,node_dao,node_hive_store toneRose
class node_gui,node_hive_menu,node_player toneIndigo
```

## Components

### Plugin entry

- [Plugin lifecycle](https://github.com/neutralplasma/magicbees/blob/main/plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt): `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt`
- [World listeners](https://github.com/neutralplasma/magicbees/tree/main/plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/listeners): `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/listeners`
- [Plugin commands](https://github.com/neutralplasma/magicbees/tree/main/plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/commands): `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/commands`

### Hive gameplay

- [Hive operations API](https://github.com/neutralplasma/magicbees/blob/main/api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/BeeHiveController.kt): `api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/BeeHiveController.kt`
- [Hive state model](https://github.com/neutralplasma/magicbees/blob/main/api/src/main/kotlin/eu/virtusdevelops/magicbees/api/models/BeeHive.kt): `api/src/main/kotlin/eu/virtusdevelops/magicbees/api/models/BeeHive.kt`
- [Hive operations](https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt`

### API services

- [Requirement parsing](https://github.com/neutralplasma/magicbees/tree/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/requirements): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/requirements`
- [Reward parsing](https://github.com/neutralplasma/magicbees/tree/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/rewards): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/rewards`
- [Provider integrations](https://github.com/neutralplasma/magicbees/tree/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/providers): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/providers`
- [Translations service](https://github.com/neutralplasma/magicbees/blob/main/api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/TranslationsController.kt): `api/src/main/kotlin/eu/virtusdevelops/magicbees/api/controllers/TranslationsController.kt`

### Hive persistence

- [Storage setup](https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/StorageController.kt): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/StorageController.kt`
- [Chunk hive cache](https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveStorageController.kt): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveStorageController.kt`
- [Hive DAO](https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/storage/BeeHiveDao.kt): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/storage/BeeHiveDao.kt`
- [Hive database](https://github.com/neutralplasma/magicbees/blob/main/core/src/main/kotlin/eu/virtusdevelops/magicbees/core/storage/mysql/BeeHiveMysql.kt): `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/storage/mysql/BeeHiveMysql.kt`

### Player interaction

- [GUI controller](https://github.com/neutralplasma/magicbees/blob/main/gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/GuiController.kt): `gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/GuiController.kt`
- [Hive menu](https://github.com/neutralplasma/magicbees/blob/main/gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/guis/BeeHiveMenu.kt): `gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/guis/BeeHiveMenu.kt`

### Other components

- **Player**
- **Minecraft server**

## Connections

- Plugin lifecycle → Storage setup: initializes (evidence: `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt`)
- Plugin lifecycle → GUI controller: initializes (evidence: `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt`)
- Plugin lifecycle → World listeners: registers (evidence: `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt`)
- Plugin lifecycle → Plugin commands: registers (evidence: `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/MagicBeesPlugin.kt`)
- Player → World listeners: interacts
- Player → Plugin commands: invokes
- World listeners → Hive operations API: uses (evidence: `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/listeners/BlockInteractListener.kt`)
- Plugin commands → Hive operations API: uses (evidence: `plugin/src/main/kotlin/eu/virtusdevelops/magicbees/plugin/commands/GiveCommand.kt`)
- Hive operations → Hive operations API: implements (evidence: `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt`)
- Hive operations → Hive state model: updates (evidence: `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt`)
- Hive operations → Chunk hive cache: delegates storage (evidence: `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveControllerImpl.kt`)
- Hive operations → Requirement parsing: evaluates
- Hive operations → Reward parsing: applies
- Storage setup → Chunk hive cache: creates (evidence: `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/StorageController.kt`)
- Storage setup → Hive DAO: initializes (evidence: `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/StorageController.kt`)
- Chunk hive cache → Hive DAO: reads writes (evidence: `core/src/main/kotlin/eu/virtusdevelops/magicbees/core/controllers/BeeHiveStorageController.kt`)
- Hive DAO → Hive database: implemented by
- GUI controller → Hive menu: manages
- Hive menu → Hive operations API: requests hive data (evidence: `gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/guis/BeeHiveMenu.kt`)
- Hive menu → Translations service: requests text (evidence: `gui/src/main/kotlin/eu/virtusdevelops/magicbees/gui/guis/BeeHiveMenu.kt`)
- Player → Hive menu: uses
- Minecraft server → Plugin lifecycle: hosts