# terranova-devs/nations architecture

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

- Interactive diagram: https://gitdiagram.com/terranova-devs/nations
- Repository: https://github.com/terranova-devs/nations

## Overview

TerraNova Nations is a Paper Minecraft plugin for managing settlements, nations, land, real estate, and settlement progression. Players use the plugin’s commands and inventory GUIs to administer these domains; region state and related domain records are persisted, with map layers reflecting region and nation changes. The tree documents integrations with WorldGuard, Pl3xMap, and Citizens, as well as Discord webhook support. Sampled source confirms selected manager-to-DAO and map-update calls; unsampled command and GUI wiring is shown only at the broad product boundary.

Main entry points: [`src/main/java/de/terranova/nations/regions/RegionManager.java`](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/regions/RegionManager.java) (Region manager), [`src/main/java/de/terranova/nations/database/dao`](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/database/dao) (Domain DAOs), [`src/main/java/de/terranova/nations/NationsPlugin.java`](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/NationsPlugin.java) (Plugin lifecycle), [`src/main/java/de/terranova/nations/command`](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/command) (Domain commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Player interface"]
  node_plugin["Plugin lifecycle<br/>[NationsPlugin.java]"]
  node_commands["Domain commands"]
  node_guis["Player GUIs"]
end

subgraph group_land["Land and access"]
  node_region_manager["Region manager<br/>[RegionManager.java]"]
  node_region_types["Region types"]
  node_region_rules["Region rules"]
  node_access["Access control"]
  node_worldguard["WorldGuard hooks"]
end

subgraph group_civic["Settlement governance"]
  node_nation_manager["Nation manager<br/>[NationManager.java]"]
  node_nation_model["Nation model<br/>[Nation.java]"]
  node_real_estate["Real estate"]
end

subgraph group_progress["Economy and progression"]
  node_bank["Settlement bank"]
  node_profession_manager["Profession manager"]
  node_profession_progress["Profession progress"]
end

subgraph group_integrations["Persistence and integrations"]
  node_map["Pl3xMap layers"]
  node_daos["Domain DAOs"]
  node_database[("SQL database<br/>[HikariCP.java]")]
end

node_player(("Player"))
node_paper(("Paper server"))
node_pl3xmap["Pl3xMap"]
node_discord["Discord webhook"]
node_citizens["Citizens NPCs"]

node_player -->|"issues commands"| node_commands
node_player -->|"uses menus"| node_guis
node_paper -->|"loads plugin"| node_plugin
node_plugin -->|"registers"| node_commands
node_plugin -->|"integrates"| node_worldguard
node_plugin -->|"integrates"| node_map
node_commands -->|"manages regions"| node_region_manager
node_commands -->|"manages nations"| node_nation_manager
node_commands -->|"manages listings"| node_real_estate
node_guis -->|"browses listings"| node_real_estate
node_guis -->|"manages nation"| node_nation_manager
node_region_manager -->|"caches and looks up"| node_region_types
node_region_manager -->|"queries regions"| node_worldguard
node_region_manager -->|"validates regions"| node_region_rules
node_region_manager -->|"loads and saves"| node_daos
node_nation_manager -->|"persists nations"| node_daos
node_nation_manager -->|"looks up settlements"| node_region_manager
node_nation_manager -->|"updates layers"| node_map
node_profession_manager -->|"removes settlement data"| node_daos
node_profession_progress -->|"reads configuration"| node_profession_manager
node_profession_progress -->|"persists progress"| node_daos
node_profession_progress -->|"charges profession cost"| node_bank
node_profession_progress -->|"updates region layer"| node_map
node_map -->|"publishes layers"| node_pl3xmap
node_daos -->|"queries and writes"| node_database
node_real_estate -->|"persists listings"| node_daos
node_region_types -.->|"uses NPC integration"| node_citizens
node_plugin -.->|"optional webhook"| node_discord

click node_plugin "https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/NationsPlugin.java"
click node_commands "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/command"
click node_guis "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/gui"
click node_region_manager "https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/regions/RegionManager.java"
click node_region_types "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions"
click node_region_rules "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/rule"
click node_access "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/modules/access"
click node_worldguard "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/worldguard"
click node_nation_manager "https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/nations/NationManager.java"
click node_nation_model "https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/nations/Nation.java"
click node_real_estate "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/modules/realEstate"
click node_bank "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/modules/bank"
click node_profession_manager "https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/professions/ProfessionManager.java"
click node_profession_progress "https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/professions/ProfessionProgressManager.java"
click node_map "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/pl3xmap"
click node_daos "https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/database/dao"
click node_database "https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/database/HikariCP.java"

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_commands,node_guis toneBlue
class node_region_manager,node_region_types,node_region_rules,node_access,node_worldguard toneAmber
class node_nation_manager,node_nation_model,node_real_estate,node_paper,node_discord toneMint
class node_bank,node_profession_manager,node_profession_progress toneRose
class node_map,node_daos,node_database,node_player,node_pl3xmap,node_citizens toneIndigo
```

## Components

### Player interface

- [Plugin lifecycle](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/NationsPlugin.java): `src/main/java/de/terranova/nations/NationsPlugin.java`
- [Domain commands](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/command): `src/main/java/de/terranova/nations/command`
- [Player GUIs](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/gui): `src/main/java/de/terranova/nations/gui`

### Land and access

- [Region manager](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/regions/RegionManager.java): `src/main/java/de/terranova/nations/regions/RegionManager.java`
- [Region types](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions): `src/main/java/de/terranova/nations/regions`
- [Region rules](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/rule): `src/main/java/de/terranova/nations/regions/rule`
- [Access control](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/modules/access): `src/main/java/de/terranova/nations/regions/modules/access`
- [WorldGuard hooks](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/worldguard): `src/main/java/de/terranova/nations/worldguard`

### Settlement governance

- [Nation manager](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/nations/NationManager.java): `src/main/java/de/terranova/nations/nations/NationManager.java`
- [Nation model](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/nations/Nation.java): `src/main/java/de/terranova/nations/nations/Nation.java`
- [Real estate](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/modules/realEstate): `src/main/java/de/terranova/nations/regions/modules/realEstate`

### Economy and progression

- [Settlement bank](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/regions/modules/bank): `src/main/java/de/terranova/nations/regions/modules/bank`
- [Profession manager](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/professions/ProfessionManager.java): `src/main/java/de/terranova/nations/professions/ProfessionManager.java`
- [Profession progress](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/professions/ProfessionProgressManager.java): `src/main/java/de/terranova/nations/professions/ProfessionProgressManager.java`

### Persistence and integrations

- [Pl3xMap layers](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/pl3xmap): `src/main/java/de/terranova/nations/pl3xmap`
- [Domain DAOs](https://github.com/terranova-devs/nations/tree/master/src/main/java/de/terranova/nations/database/dao): `src/main/java/de/terranova/nations/database/dao`
- [SQL database](https://github.com/terranova-devs/nations/blob/master/src/main/java/de/terranova/nations/database/HikariCP.java): `src/main/java/de/terranova/nations/database/HikariCP.java`

### Other components

- **Player**
- **Paper server**
- **Pl3xMap**
- **Discord webhook**
- **Citizens NPCs**

## Connections

- Player → Domain commands: issues commands
- Player → Player GUIs: uses menus
- Paper server → Plugin lifecycle: loads plugin
- Plugin lifecycle → Domain commands: registers
- Plugin lifecycle → WorldGuard hooks: integrates
- Plugin lifecycle → Pl3xMap layers: integrates
- Domain commands → Region manager: manages regions
- Domain commands → Nation manager: manages nations
- Domain commands → Real estate: manages listings
- Player GUIs → Real estate: browses listings
- Player GUIs → Nation manager: manages nation
- Region manager → Region types: caches and looks up
- Region manager → WorldGuard hooks: queries regions
- Region manager → Region rules: validates regions
- Region manager → Domain DAOs: loads and saves
- Nation manager → Domain DAOs: persists nations
- Nation manager → Region manager: looks up settlements
- Nation manager → Pl3xMap layers: updates layers
- Profession manager → Domain DAOs: removes settlement data
- Profession progress → Profession manager: reads configuration
- Profession progress → Domain DAOs: persists progress
- Profession progress → Settlement bank: charges profession cost
- Profession progress → Pl3xMap layers: updates region layer
- Pl3xMap layers → Pl3xMap: publishes layers
- Domain DAOs → SQL database: queries and writes
- Real estate → Domain DAOs: persists listings
- Region types → Citizens NPCs: uses NPC integration
- Plugin lifecycle → Discord webhook: optional webhook