# groupez-dev/zauctionhouse architecture

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

- Interactive diagram: https://gitdiagram.com/groupez-dev/zauctionhouse
- Repository: https://github.com/groupez-dev/zauctionhouse

## Overview

1. **What this repo is**
   - zAuctionHouse V4 is a **Minecraft auction-house plugin** for Spigot/Paper, written in **Java 21** and built with **Gradle Kotlin DSL**.
   - The repository is split into a **core plugin**, an **API module**, and many **optional hook modules** for third-party integrations.

2. **Top-level architecture**
   - The runtime center is the **core plugin** under `src/main/java/fr/maxlego08/zauctionhouse`.
   - The **API module** under `API/` defines the public contracts and shared abstractions.
   - The **Hooks/** subprojects are optional add-ons that extend item compatibility, permissions, or migration support.

3. **Main runtime entrypoints**
   - `ZAuctionPlugin` and `ZAuctionManager` are the primary plugin bootstrap/coordination classes.
   - Event listeners such as `PlayerListener` and `ChatSearchListener` bridge Minecraft events into the auction system.
   - Command handling is centralized through `ZCommandManager` and the `command/commands` tree.

4. **Core business services**
   - The main business flows are isolated in `services/`: `SellService`, `PurchaseService`, `ClaimService`, `RemoveService`, `ExpireService`, `SearchService`, and `HistoryService`.
   - Each service encapsulates one auction action and returns typed result objects for success/failure handling.
   - This makes the core flow: **command or GUI action -> service -> storage/economy/rules -> result**.

5. **Auction domain model**
   - The domain is built around items, listings, and transaction history.
   - Key packages include `items/`, `category/`, `economy/`, `tax/`, `rule/`, `placeholder/`, and `storage/repository/`.
   - Item eligibility is controlled by rule objects such as material/name/lore/model/tag-based rules, while categories and sort/filter models organize browsing.

6. **GUI and user interaction layer**
   - The player-facing UI is implemented with a **zMenu-style inventory system**: loaders assemble menus, and buttons handle actions.
   - GUI code lives in `loader/` and `buttons/`, with separate screens for auction browsing, selling, confirms, history, admin views, and shulker contents.
   - Configuration-driven inventory layouts come from YAML files in `src/main/resources/**/inventories/`.

7. **Configuration and localization**
   - The plugin is heavily data-driven through YAML: `config.yml`, `categories.yml`, `rules.yml`, `economies.yml`, `messages.yml`, `discord.yml`, and `patterns/`.
   - Locale folders like `fr/`, `es/`, `it/`, and `th/` contain translated config and GUI definitions.
   - This means most UI text, button placement, and behavior tuning are externalized rather than hardcoded.

8. **Persistence and data access**
   - Persistent state is handled through `storage/` with a repository pattern: `AuctionItemRepository`, `ItemRepository`, `PlayerRepository`, `LogRepository`, and `TransactionRepository`.
   - `ZStorageManager` and `GlobalDatabaseConfiguration` coordinate database access, while `migrations/` defines schema creation.
   - DTO classes in `storage/repository` and `API/storage/dto` separate database shape from runtime domain objects.

9. **Caching and performance boundaries**
   - The plugin uses several caches under `utils/cache/` and API cache types to reduce repeated database and item-processing cost.
   - Search/sort/pagination are likely cache-sensitive paths, which is consistent with the presence of `SortedItemsCache`, `ExpiringCache`, and player caches.
   - Performance-related helpers and debug utilities are part of the core, not just operational tooling.

10. **Economy, tax, and permissions flow**
   - Economy is abstracted through `economy/` and `api/economy/`, allowing multiple currencies or economy backends.
   - Taxes are a separate subsystem under `tax/`, and permission-driven reductions are supported.
   - Permission checks and offline permission support are isolated so economy and auction logic stay independent of any one permission plugin.

11. **Integrations and external services**
   - Placeholder expansion is supported through dedicated placeholder registries and resolvers.
   - Discord notifications are handled by `discord/`, with webhook-based sale alerts and embed formatting.
   - Item-content and custom-item compatibility are abstracted so the core auction logic can work with vanilla items and plugin-provided items.

12. **Hook modules**
   - Each folder under `Hooks/` is a small adapter module for a specific third-party plugin such as ItemsAdder, Oraxen, MMOItems, Slimefun, HeadDatabase, Nexo, Nova, CraftEngine, ExecutableItems, and ExecutableBlocks.
   - Most hooks provide either a **rule loader** or a **content provider**, which plugs into the core rule/content system without coupling the main plugin to those dependencies.
   - The `Hooks/ZelAuction` module is specifically for **migration/import from the older V3 product**.

13. **Migration and legacy compatibility**
   - There is a dedicated migration pipeline in `migration/` and `API/migration/`.
   - V3 import support is modeled as readers/providers over different legacy storage formats, including SQL and JSON.
   - This is a one-way data import boundary: legacy data is translated into the new repository/domain model.

14. **Multi-server / cluster support**
   - The API and core both contain cluster bridge abstractions and lock tokens, indicating support for coordinated operations across servers.
   - The architecture is designed so distributed synchronization can be added without rewriting auction actions or storage semantics.
   - In diagram terms, this is a separate cross-server coordination layer around the same core services and repositories.

15. **How the main flow hangs together**
   - A player command or GUI click enters the command/UI layer, passes through validation/rules/caches, and invokes a service.
   - The service consults economy, tax, permission, item-content, and placeholder subsystems as needed.
   - Successful actions persist through repositories, update caches, and may emit events, Discord notifications, or cross-server sync signals.

Main entry points: [`src/main/java/fr/maxlego08/zauctionhouse/services/AuctionService.java`](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/services/AuctionService.java) (Auction services), [`API/src/main/java/fr/maxlego08/zauctionhouse/api/AuctionPlugin.java`](https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/AuctionPlugin.java) (API root), [`src/main/java/fr/maxlego08/zauctionhouse/ZAuctionManager.java`](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/ZAuctionManager.java) (Manager), [`src/main/java/fr/maxlego08/zauctionhouse/loader/ZInventoriesLoader.java`](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/loader/ZInventoriesLoader.java) (Inventory UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Plugin"]
  node_plugin["Plugin bootstrap<br/>plugin entrypoint"]
  node_manager["Manager<br/>runtime coordinator"]
  node_commands["Command manager<br/>command router"]
  node_ui["Inventory UI<br/>inventory loader"]
  node_listeners["Event listeners<br/>event bridge"]
  node_services["Auction services<br/>business services"]
  node_rules["Rule engine<br/>eligibility rules"]
  node_economy["Economy<br/>pricing backend"]
  node_tax["Tax config<br/>fee rules"]
  node_storage[("Storage<br/>repositories")]
  node_items["Items<br/>domain model<br/>[ZAuctionItem.java]"]
  node_cache["Caches<br/>performance layer"]
  node_discord["Discord<br/>notifications"]
  node_migration["Migration<br/>legacy import"]
end

subgraph group_api["API Module"]
  node_api_root["API root<br/>public contracts<br/>[AuctionPlugin.java]"]
  node_api_services["Service API<br/>service contracts"]
  node_api_storage[("Storage API<br/>storage contracts<br/>[Repository.java]")]
  node_api_rules["Rules API<br/>rule contracts<br/>[RuleLoader.java]"]
  node_api_hooks["Hook API<br/>integration contracts"]
  node_api_cluster["Cluster API<br/>cross-server bridge"]
end

subgraph group_hooks["Hook Modules"]
  node_hook_itemsadder["ItemsAdder<br/>content hook"]
  node_hook_oraxen["Oraxen<br/>content hook"]
  node_hook_mmoitems["MMOItems<br/>content hook"]
  node_hook_luckperms["LuckPerms<br/>permission hook"]
  node_hook_zelauction["ZelAuction<br/>migration hook"]
end

subgraph group_resources["Data Files"]
  node_config["Config files<br/>yaml settings<br/>[config.yml]"]
  node_inventories["Inventory layouts<br/>yaml ui layouts<br/>[auction.yml]"]
  node_locales["Locales<br/>translations<br/>[messages.yml]"]
  node_pluginyml["Plugin descriptor<br/>plugin metadata<br/>[plugin.yml]"]
end

node_plugin -->|"boots"| node_manager
node_manager -->|"wires"| node_commands
node_manager -->|"loads"| node_ui
node_manager -->|"registers"| node_listeners
node_manager -->|"coordinates"| node_services
node_commands -->|"invokes"| node_services
node_ui -->|"invokes"| node_services
node_listeners -->|"triggers"| node_services
node_services -->|"validates"| node_rules
node_services -->|"prices"| node_economy
node_services -->|"applies"| node_tax
node_services -->|"persists"| node_storage
node_services -->|"updates"| node_cache
node_services -->|"notifies"| node_discord
node_services -->|"uses"| node_items
node_migration -->|"imports"| node_storage
node_hook_itemsadder -->|"extends"| node_api_rules
node_hook_oraxen -->|"extends"| node_api_rules
node_hook_mmoitems -->|"extends"| node_api_rules
node_hook_luckperms -->|"implements"| node_api_hooks
node_hook_zelauction -->|"feeds"| node_migration
node_api_root -->|"defines"| node_api_services
node_api_root -->|"defines"| node_api_storage
node_api_root -->|"defines"| node_api_rules
node_api_root -->|"defines"| node_api_hooks
node_api_root -->|"defines"| node_api_cluster
node_config -->|"drives"| node_ui
node_inventories -->|"drives"| node_ui
node_locales -->|"localizes"| node_ui
node_pluginyml -->|"declares"| node_plugin

click node_plugin "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/ZAuctionPlugin.java"
click node_manager "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/ZAuctionManager.java"
click node_commands "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/command/ZCommandManager.java"
click node_ui "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/loader/ZInventoriesLoader.java"
click node_listeners "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/listeners/PlayerListener.java"
click node_services "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/services/AuctionService.java"
click node_rules "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/rule/ZItemRuleManager.java"
click node_economy "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/economy/ZEconomyManager.java"
click node_tax "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/tax/ZTaxConfiguration.java"
click node_storage "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/storage/ZStorageManager.java"
click node_items "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/items/ZAuctionItem.java"
click node_cache "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/utils/cache/SortedItemsCache.java"
click node_discord "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/discord/DiscordWebhookService.java"
click node_migration "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/migration/ZMigrationRegistry.java"
click node_api_root "https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/AuctionPlugin.java"
click node_api_services "https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/services/AuctionSellService.java"
click node_api_storage "https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/storage/Repository.java"
click node_api_rules "https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/rules/loader/RuleLoader.java"
click node_api_hooks "https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/hooks/itemcontent/ItemContentManager.java"
click node_api_cluster "https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/cluster/AuctionClusterBridge.java"
click node_hook_itemsadder "https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/ItemsAdder/src/main/java/fr/maxlego08/zauctionhouse/hooks/itemsadder/ItemsAdderRuleLoader.java"
click node_hook_oraxen "https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/Oraxen/src/main/java/fr/maxlego08/zauctionhouse/hooks/oraxen/OraxenRuleLoader.java"
click node_hook_mmoitems "https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/MMOItems/src/main/java/fr/maxlego08/zauctionhouse/hooks/mmoitems/MMOItemsRuleLoader.java"
click node_hook_luckperms "https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/LuckPerms/src/main/java/fr/maxlego08/zauctionhouse/hooks/permissions/LuckPermsOfflinePermission.java"
click node_hook_zelauction "https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/ZelAuction/src/main/java/fr/maxlego08/zauctionhouse/hooks/zelauction/ZelAuctionMigrationService.java"
click node_config "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/config.yml"
click node_inventories "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/inventories/auction.yml"
click node_locales "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/fr/messages.yml"
click node_pluginyml "https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/plugin.yml"

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_manager,node_commands,node_ui,node_listeners,node_services,node_rules,node_economy,node_tax,node_storage,node_items,node_cache,node_discord,node_migration toneBlue
class node_api_root,node_api_services,node_api_storage,node_api_rules,node_api_hooks,node_api_cluster toneAmber
class node_hook_itemsadder,node_hook_oraxen,node_hook_mmoitems,node_hook_luckperms,node_hook_zelauction toneMint
class node_config,node_inventories,node_locales,node_pluginyml toneRose
```

## Components

### Core Plugin

Runtime plugin, services, UI, storage, and integrations

- [Plugin bootstrap](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/ZAuctionPlugin.java): plugin entrypoint · Main plugin lifecycle and wiring · `src/main/java/fr/maxlego08/zauctionhouse/ZAuctionPlugin.java`
- [Manager](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/ZAuctionManager.java): runtime coordinator · Central bootstrap and subsystem wiring · `src/main/java/fr/maxlego08/zauctionhouse/ZAuctionManager.java`
- [Command manager](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/command/ZCommandManager.java): command router · Dispatches player and admin commands · `src/main/java/fr/maxlego08/zauctionhouse/command/ZCommandManager.java`
- [Inventory UI](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/loader/ZInventoriesLoader.java): inventory loader · Loads menus and routes button actions · `src/main/java/fr/maxlego08/zauctionhouse/loader/ZInventoriesLoader.java`
- [Event listeners](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/listeners/PlayerListener.java): event bridge · Bridges Minecraft events into auction flows · `src/main/java/fr/maxlego08/zauctionhouse/listeners/PlayerListener.java`
- [Auction services](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/services/AuctionService.java): business services · Sell, purchase, claim, remove, expire, search, history · `src/main/java/fr/maxlego08/zauctionhouse/services/AuctionService.java`
- [Rule engine](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/rule/ZItemRuleManager.java): eligibility rules · Material, name, lore, model, tag, and combined rule evaluation · `src/main/java/fr/maxlego08/zauctionhouse/rule/ZItemRuleManager.java`
- [Economy](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/economy/ZEconomyManager.java): pricing backend · Auction pricing and currency abstraction · `src/main/java/fr/maxlego08/zauctionhouse/economy/ZEconomyManager.java`
- [Tax config](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/tax/ZTaxConfiguration.java): fee rules · Tax calculation and reductions · `src/main/java/fr/maxlego08/zauctionhouse/tax/ZTaxConfiguration.java`
- [Storage](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/storage/ZStorageManager.java): repositories · Database manager, migrations, and repositories · `src/main/java/fr/maxlego08/zauctionhouse/storage/ZStorageManager.java`
- [Items](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/items/ZAuctionItem.java): domain model · Auction item wrappers and item-content handling · `src/main/java/fr/maxlego08/zauctionhouse/items/ZAuctionItem.java`
- [Caches](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/utils/cache/SortedItemsCache.java): performance layer · Expiring, sorted, and player caches · `src/main/java/fr/maxlego08/zauctionhouse/utils/cache/SortedItemsCache.java`
- [Discord](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/discord/DiscordWebhookService.java): notifications · Webhook notifications and placeholder resolution · `src/main/java/fr/maxlego08/zauctionhouse/discord/DiscordWebhookService.java`
- [Migration](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/java/fr/maxlego08/zauctionhouse/migration/ZMigrationRegistry.java): legacy import · V3 import pipeline and legacy readers · `src/main/java/fr/maxlego08/zauctionhouse/migration/ZMigrationRegistry.java`

### API Module

Public contracts shared by core and hooks

- [API root](https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/AuctionPlugin.java): public contracts · Shared plugin, manager, and loader interfaces · `API/src/main/java/fr/maxlego08/zauctionhouse/api/AuctionPlugin.java`
- [Service API](https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/services/AuctionSellService.java): service contracts · Public auction service interfaces and result types · `API/src/main/java/fr/maxlego08/zauctionhouse/api/services/AuctionSellService.java`
- [Storage API](https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/storage/Repository.java): storage contracts · Repository and DTO abstractions · `API/src/main/java/fr/maxlego08/zauctionhouse/api/storage/Repository.java`
- [Rules API](https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/rules/loader/RuleLoader.java): rule contracts · Rule loaders, contexts, and registry APIs · `API/src/main/java/fr/maxlego08/zauctionhouse/api/rules/loader/RuleLoader.java`
- [Hook API](https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/hooks/itemcontent/ItemContentManager.java): integration contracts · Item content and offline permission abstractions · `API/src/main/java/fr/maxlego08/zauctionhouse/api/hooks/itemcontent/ItemContentManager.java`
- [Cluster API](https://github.com/groupez-dev/zauctionhouse/blob/main/API/src/main/java/fr/maxlego08/zauctionhouse/api/cluster/AuctionClusterBridge.java): cross-server bridge · Distributed coordination and lock tokens · `API/src/main/java/fr/maxlego08/zauctionhouse/api/cluster/AuctionClusterBridge.java`

### Hook Modules

Optional adapters for third-party plugins and migration

- [ItemsAdder](https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/ItemsAdder/src/main/java/fr/maxlego08/zauctionhouse/hooks/itemsadder/ItemsAdderRuleLoader.java): content hook · Content/rule adapter for ItemsAdder · `Hooks/ItemsAdder/src/main/java/fr/maxlego08/zauctionhouse/hooks/itemsadder/ItemsAdderRuleLoader.java`
- [Oraxen](https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/Oraxen/src/main/java/fr/maxlego08/zauctionhouse/hooks/oraxen/OraxenRuleLoader.java): content hook · Content/rule adapter for Oraxen · `Hooks/Oraxen/src/main/java/fr/maxlego08/zauctionhouse/hooks/oraxen/OraxenRuleLoader.java`
- [MMOItems](https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/MMOItems/src/main/java/fr/maxlego08/zauctionhouse/hooks/mmoitems/MMOItemsRuleLoader.java): content hook · Content/rule adapter for MMOItems · `Hooks/MMOItems/src/main/java/fr/maxlego08/zauctionhouse/hooks/mmoitems/MMOItemsRuleLoader.java`
- [LuckPerms](https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/LuckPerms/src/main/java/fr/maxlego08/zauctionhouse/hooks/permissions/LuckPermsOfflinePermission.java): permission hook · Offline permission integration · `Hooks/LuckPerms/src/main/java/fr/maxlego08/zauctionhouse/hooks/permissions/LuckPermsOfflinePermission.java`
- [ZelAuction](https://github.com/groupez-dev/zauctionhouse/blob/main/Hooks/ZelAuction/src/main/java/fr/maxlego08/zauctionhouse/hooks/zelauction/ZelAuctionMigrationService.java): migration hook · Legacy V3 migration/import adapter · `Hooks/ZelAuction/src/main/java/fr/maxlego08/zauctionhouse/hooks/zelauction/ZelAuctionMigrationService.java`

### Data Files

Yaml-driven configuration, locales, and inventory layouts

- [Config files](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/config.yml): yaml settings · Main plugin configuration and shared data files · `src/main/resources/config.yml`
- [Inventory layouts](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/inventories/auction.yml): yaml ui layouts · GUI definitions for player and admin screens · `src/main/resources/inventories/auction.yml`
- [Locales](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/fr/messages.yml): translations · Language-specific configs, messages, and inventories · `src/main/resources/fr/messages.yml`
- [Plugin descriptor](https://github.com/groupez-dev/zauctionhouse/blob/main/src/main/resources/plugin.yml): plugin metadata · Server plugin metadata and main class declaration · `src/main/resources/plugin.yml`

## Connections

- Plugin bootstrap → Manager: boots · Plugin lifecycle delegates to the manager
- Manager → Command manager: wires · Registers command handling
- Manager → Inventory UI: loads · Initializes inventory loaders
- Manager → Event listeners: registers · Hooks player and chat events
- Manager → Auction services: coordinates · Routes user actions into services
- Command manager → Auction services: invokes · Command actions call auction services
- Inventory UI → Auction services: invokes · GUI buttons trigger service actions
- Event listeners → Auction services: triggers · Event-driven actions enter business services
- Auction services → Rule engine: validates · Item eligibility and action constraints
- Auction services → Economy: prices · Handles currency and payment logic
- Auction services → Tax config: applies · Computes fees and reductions
- Auction services → Storage: persists · Reads and writes auction state
- Auction services → Caches: updates · Keeps hot data and sorted views current
- Auction services → Discord: notifies · Emits sale and action notifications
- Auction services → Items: uses · Operates on auction item models
- Migration → Storage: imports · Translates legacy data into new storage
- ItemsAdder → Rules API: extends · Registers external item rules
- Oraxen → Rules API: extends · Registers external item rules
- MMOItems → Rules API: extends · Registers external item rules
- LuckPerms → Hook API: implements · Provides offline permission support
- ZelAuction → Migration: feeds · Provides legacy import support
- API root → Service API: defines · Public service contracts
- API root → Storage API: defines · Public storage contracts
- API root → Rules API: defines · Public rule contracts
- API root → Hook API: defines · Public integration contracts
- API root → Cluster API: defines · Public cluster coordination contracts
- Config files → Inventory UI: drives · External YAML defines UI behavior
- Inventory layouts → Inventory UI: drives · Inventory layouts are config-driven
- Locales → Inventory UI: localizes · Translations supply text and layouts
- Plugin descriptor → Plugin bootstrap: declares · Server metadata points to the main plugin class
