DUXPLIMA Documentation

Architecture

Hexagonal layers, CQRS commands, and why the API looks the way it does.

uxmClaims is a hexagonal (ports and adapters) application with a split between reads and writes. The shape explains why the API is a facade taking command objects rather than a set of setters.

The modules

ModuleContainsDepends on
uxmclaims-domainThe model (Claim and its parts), the enums, the events, ClaimExceptionnothing
uxmclaims-appThe facade interfaces, the command objects, the ports, the config modelsdomain
uxmclaims-coreThe use-case services behind the facades, ClaimPermissionPolicyapp, domain
uxmclaims-infraThe jOOQ repositories, the in-memory cache, migrations, the server lease, locks, cooldowns, webhooksapp, domain
uxmclaims-platform:apiUxmClaimBukkitAPI, @ClaimEventHandler, BukkitConverter; published as bukkit-apiapp, domain
uxmclaims-platform:adaptersThe Bukkit adapters for the ports: economy, permissions, regions, placeholders, web maps, the event busapp, domain, api
uxmclaims-platform:coreCommands, menus, listeners, wiringeverything above
uxmclaims-platform:dialog-*, :bedrockJava dialog screens and Bedrock forms, loaded only where the server supports themdialog-api
uxmclaims-platform:bukkit, :foliaThe two plugin jars and their schedulerscore

You compile against bukkit-api, which brings uxmclaims-app and uxmclaims-domain with it. See Adding the dependency.

Nothing in domain knows Bukkit exists, which is what makes the rules testable without a server.

Ports and adapters

A port is an interface the application needs. An adapter implements it for one platform or plugin.

PortAdapters
EconomyPortVaultEconomy, NoopEconomy
PermissionPortLuckPermsPermission, NoopPermission
RegionPortWorldGuardRegion, NoopRegion
PlaceholderPortPlaceholderAPIPort, NoopPlaceholderPort
MapVisualizerPortDynmapVisualizer, BlueMapVisualizer, Pl3xMapVisualizer, SquareMapVisualizer, NoopMapVisualizer
EventBusPortBukkitEventBus
ClaimRepositoryPortCompositeClaimRepository (a MemoryClaimRepository cache in front of JooqClaimRepository)
LockingPort / CooldownPortLocalLockAdapter / InMemoryCooldownAdapter
WebhookPortDiscordWebhook

Every integration port has a Noop adapter. That is why the plugin runs with none of its soft dependencies installed: a missing integration is an adapter that does nothing. Which adapter is used is decided once, at startup; see Integrations.

Commands and queries

Queries are plain methods that read the in-memory cache:

Optional<Claim> claim = claimFacade.findByChunk(BukkitConverter.toDomainChunk(bukkitChunk));
List<Claim> owned     = claimFacade.findByOwnerUid(uuid);
int count             = claimFacade.countByOwnerUid(uuid);

Commands are objects describing an intent, handed to the facade:

ClaimRenameCommand command = ClaimRenameCommand.builder()
        .claimId(claim.getId())
        .actorUid(player.getUniqueId())
        .name("New name")
        .build();

Claim renamed = claimFacade.renameClaim(command);

The command carries the actor, so one code path enforces permissions, charges the economy, fires the event and posts the webhook, instead of every caller remembering to.

The write path

StepWhat happens
1Takes a lock on the claim (local to this server, five-second timeout) and loads a copy
2Checks permissions, cooldown, balance, limits and regions, as the options allow
3Applies the change to the copy
4Publishes the events; a cancellation aborts here
5Charges the actor, then saves in one transaction, refunding if the save fails
6Posts the webhook and starts the cooldown

Each check in step 2 and each action in step 6 is a side effect you can switch off per call with ClaimCommandOptions. This is how an admin tool or a migration script creates claims without charging anyone, spamming Discord or tripping a limit. The effects and presets are listed in The API.

Because the cache and the locks live inside one server, a database belongs to one server at a time; see Database.

Related: The API, Events, Domain model