How groupez-dev/zauctionhouse works
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: AuctionService.java Auction services · AuctionPlugin.java API root · ZAuctionManager.java Manager · ZInventoriesLoader.java Inventory UI
Components 29
Core Plugin
Runtime plugin, services, UI, storage, and integrations
- Plugin bootstrap · Main plugin lifecycle and wiring
src/main/java/fr/maxlego08/zauctionhouse/ZAuctionPlugin.java - Manager · Central bootstrap and subsystem wiring
src/main/java/fr/maxlego08/zauctionhouse/ZAuctionManager.java - Command manager · Dispatches player and admin commands
src/main/java/fr/maxlego08/zauctionhouse/command/ZCommandManager.java - Inventory UI · Loads menus and routes button actions
src/main/java/fr/maxlego08/zauctionhouse/loader/ZInventoriesLoader.java - Event listeners · Bridges Minecraft events into auction flows
src/main/java/fr/maxlego08/zauctionhouse/listeners/PlayerListener.java - Auction services · Sell, purchase, claim, remove, expire, search, history
src/main/java/fr/maxlego08/zauctionhouse/services/AuctionService.java - Rule engine · Material, name, lore, model, tag, and combined rule evaluation
src/main/java/fr/maxlego08/zauctionhouse/rule/ZItemRuleManager.java - Economy · Auction pricing and currency abstraction
src/main/java/fr/maxlego08/zauctionhouse/economy/ZEconomyManager.java - Tax config · Tax calculation and reductions
src/main/java/fr/maxlego08/zauctionhouse/tax/ZTaxConfiguration.java - Storage · Database manager, migrations, and repositories
src/main/java/fr/maxlego08/zauctionhouse/storage/ZStorageManager.java - Items · Auction item wrappers and item-content handling
src/main/java/fr/maxlego08/zauctionhouse/items/ZAuctionItem.java - Caches · Expiring, sorted, and player caches
src/main/java/fr/maxlego08/zauctionhouse/utils/cache/SortedItemsCache.java - Discord · Webhook notifications and placeholder resolution
src/main/java/fr/maxlego08/zauctionhouse/discord/DiscordWebhookService.java - Migration · 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 · Shared plugin, manager, and loader interfaces
API/src/main/java/fr/maxlego08/zauctionhouse/api/AuctionPlugin.java - Service API · Public auction service interfaces and result types
API/src/main/java/fr/maxlego08/zauctionhouse/api/services/AuctionSellService.java - Storage API · Repository and DTO abstractions
API/src/main/java/fr/maxlego08/zauctionhouse/api/storage/Repository.java - Rules API · Rule loaders, contexts, and registry APIs
API/src/main/java/fr/maxlego08/zauctionhouse/api/rules/loader/RuleLoader.java - Hook API · Item content and offline permission abstractions
API/src/main/java/fr/maxlego08/zauctionhouse/api/hooks/itemcontent/ItemContentManager.java - Cluster API · 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 · Content/rule adapter for ItemsAdder
Hooks/ItemsAdder/src/main/java/fr/maxlego08/zauctionhouse/hooks/itemsadder/ItemsAdderRuleLoader.java - Oraxen · Content/rule adapter for Oraxen
Hooks/Oraxen/src/main/java/fr/maxlego08/zauctionhouse/hooks/oraxen/OraxenRuleLoader.java - MMOItems · Content/rule adapter for MMOItems
Hooks/MMOItems/src/main/java/fr/maxlego08/zauctionhouse/hooks/mmoitems/MMOItemsRuleLoader.java - LuckPerms · Offline permission integration
Hooks/LuckPerms/src/main/java/fr/maxlego08/zauctionhouse/hooks/permissions/LuckPermsOfflinePermission.java - ZelAuction · 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 · Main plugin configuration and shared data files
src/main/resources/config.yml - Inventory layouts · GUI definitions for player and admin screens
src/main/resources/inventories/auction.yml - Locales · Language-specific configs, messages, and inventories
src/main/resources/fr/messages.yml - Plugin descriptor · Server plugin metadata and main class declaration
src/main/resources/plugin.yml
Connections 30
- 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