# xpdustry/imperium architecture

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

- Interactive diagram: https://gitdiagram.com/xpdustry/imperium
- Repository: https://github.com/xpdustry/imperium

## Overview

Imperium is the core of the Chaotic server network: a shared Kotlin service layer with a Mindustry server plugin and a Discord/web backend. The main user-facing workflow spans player connection and account/session handling, in-game commands and chat, and cross-server or Discord coordination; moderation, maps, history, and metrics are additional product branches. The graph reflects the supplied tree, README, and sampled source; unsampled features are represented by their existing source paths, while uncertain wiring is omitted.

Main entry points: [`imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/AccountService.kt`](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/AccountService.kt) (Account service), [`imperium-common/src/main/kotlin/com/xpdustry/imperium/common/message/SQLMessageService.kt`](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/message/SQLMessageService.kt) (Message service), [`imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/MindustrySessionService.kt`](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/MindustrySessionService.kt) (Session service), [`imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/store/DataStoreService.kt`](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/store/DataStoreService.kt) (Player data cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shared runtime"]
  node_sql[("SQL database<br/>[SQLDatabaseImpl.kt]")]
  node_message_service["Message service"]
end

subgraph group_accounts["Accounts and identity"]
  node_account_listener["Account events<br/>[AccountListener.kt]"]
  node_account_commands["Account commands<br/>[AccountCommand.kt]"]
  node_login["Login and register<br/>[LoginWindow.kt]"]
  node_session_service["Session service"]
  node_account_service["Account service<br/>[AccountService.kt]"]
  node_data_store["Player data cache"]
end

subgraph group_mindustry["Mindustry server"]
  node_mindustry["Mindustry plugin<br/>[ImperiumPlugin.kt]"]
  node_chat_pipeline["Chat pipeline"]
  node_chat_bridge["Chat bridge"]
  node_history["Game history<br/>[Historian.kt]"]
  node_gatekeeper["Connection gatekeeper"]
end

subgraph group_backend["Discord backend"]
  node_bridge_listener["Mindustry bridge"]
  node_discord_service["Discord service<br/>[DiscordService.kt]"]
  node_discord_commands["Discord commands"]
  node_map_features["Map management<br/>[MapCommand.kt]"]
  node_moderation["Moderation and reports"]
end

subgraph group_operations["Operations"]
  node_metrics["Metrics collection"]
  node_block_monitor["Stall monitoring"]
  node_webhook["Webhook service"]
end

node_players(("Mindustry players"))
node_discord_users(("Discord users"))
node_discord(("Discord platform"))

node_players -->|"authenticate"| node_login
node_players -->|"invoke"| node_account_commands
node_login -->|"login session"| node_session_service
node_account_commands -->|"manage account"| node_account_service
node_session_service -->|"lookup account"| node_account_service
node_session_service -->|"read and write"| node_sql
node_account_service -->|"read and write"| node_sql
node_data_store -->|"load session"| node_session_service
node_data_store -->|"load account"| node_account_service
node_data_store -->|"subscribe updates"| node_message_service
node_account_service -->|"broadcast updates"| node_message_service
node_message_service -->|"queue messages"| node_sql
node_players -->|"send chat"| node_chat_pipeline
node_chat_bridge -->|"exchange messages"| node_message_service
node_bridge_listener -->|"subscribe messages"| node_message_service
node_discord_commands -->|"check permissions"| node_discord_service
node_discord_users -->|"invoke"| node_discord_commands
node_discord_service -->|"connect and manage roles"| node_discord
node_block_monitor -->|"send alert"| node_webhook

click node_mindustry "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/ImperiumPlugin.kt"
click node_account_listener "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/AccountListener.kt"
click node_account_commands "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/AccountCommand.kt"
click node_login "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/LoginWindow.kt"
click node_session_service "https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/MindustrySessionService.kt"
click node_account_service "https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/AccountService.kt"
click node_data_store "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/store/DataStoreService.kt"
click node_sql "https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/database/SQLDatabaseImpl.kt"
click node_message_service "https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/message/SQLMessageService.kt"
click node_chat_pipeline "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/chat/MindustryMessagePipeline.kt"
click node_chat_bridge "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/chat/BridgeChatMessageListener.kt"
click node_bridge_listener "https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/bridge/MindustryBridgeListener.kt"
click node_discord_service "https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/service/DiscordService.kt"
click node_discord_commands "https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/command/DiscordCommandDispatcher.kt"
click node_map_features "https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/commands/MapCommand.kt"
click node_moderation "https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/commands/ModerationCommand.kt"
click node_history "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/history/Historian.kt"
click node_gatekeeper "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/security/GatekeeperPipeline.kt"
click node_metrics "https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/metrics/MetricsCollector.kt"
click node_block_monitor "https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/monitoring/BlockHoundService.kt"
click node_webhook "https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/webhook/WebhookMessageSender.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_sql,node_message_service,node_discord_users toneBlue
class node_account_listener,node_account_commands,node_login,node_session_service,node_account_service,node_data_store toneAmber
class node_mindustry,node_chat_pipeline,node_chat_bridge,node_history,node_gatekeeper toneMint
class node_bridge_listener,node_discord_service,node_discord_commands,node_map_features,node_moderation toneRose
class node_metrics,node_block_monitor,node_webhook,node_players,node_discord toneIndigo
```

## Components

### Shared runtime

- [SQL database](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/database/SQLDatabaseImpl.kt): `imperium-common/src/main/kotlin/com/xpdustry/imperium/common/database/SQLDatabaseImpl.kt`
- [Message service](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/message/SQLMessageService.kt): `imperium-common/src/main/kotlin/com/xpdustry/imperium/common/message/SQLMessageService.kt`

### Accounts and identity

- [Account events](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/AccountListener.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/AccountListener.kt`
- [Account commands](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/AccountCommand.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/AccountCommand.kt`
- [Login and register](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/LoginWindow.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/account/LoginWindow.kt`
- [Session service](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/MindustrySessionService.kt): `imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/MindustrySessionService.kt`
- [Account service](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/AccountService.kt): `imperium-common/src/main/kotlin/com/xpdustry/imperium/common/account/AccountService.kt`
- [Player data cache](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/store/DataStoreService.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/store/DataStoreService.kt`

### Mindustry server

- [Mindustry plugin](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/ImperiumPlugin.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/ImperiumPlugin.kt`
- [Chat pipeline](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/chat/MindustryMessagePipeline.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/chat/MindustryMessagePipeline.kt`
- [Chat bridge](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/chat/BridgeChatMessageListener.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/chat/BridgeChatMessageListener.kt`
- [Game history](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/history/Historian.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/history/Historian.kt`
- [Connection gatekeeper](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/security/GatekeeperPipeline.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/security/GatekeeperPipeline.kt`

### Discord backend

- [Mindustry bridge](https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/bridge/MindustryBridgeListener.kt): `imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/bridge/MindustryBridgeListener.kt`
- [Discord service](https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/service/DiscordService.kt): `imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/service/DiscordService.kt`
- [Discord commands](https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/command/DiscordCommandDispatcher.kt): `imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/command/DiscordCommandDispatcher.kt`
- [Map management](https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/commands/MapCommand.kt): `imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/commands/MapCommand.kt`
- [Moderation and reports](https://github.com/xpdustry/imperium/blob/master/imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/commands/ModerationCommand.kt): `imperium-backend/src/main/kotlin/com/xpdustry/imperium/backend/commands/ModerationCommand.kt`

### Operations

- [Metrics collection](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/metrics/MetricsCollector.kt): `imperium-common/src/main/kotlin/com/xpdustry/imperium/common/metrics/MetricsCollector.kt`
- [Stall monitoring](https://github.com/xpdustry/imperium/blob/master/imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/monitoring/BlockHoundService.kt): `imperium-mindustry/src/main/kotlin/com/xpdustry/imperium/mindustry/monitoring/BlockHoundService.kt`
- [Webhook service](https://github.com/xpdustry/imperium/blob/master/imperium-common/src/main/kotlin/com/xpdustry/imperium/common/webhook/WebhookMessageSender.kt): `imperium-common/src/main/kotlin/com/xpdustry/imperium/common/webhook/WebhookMessageSender.kt`

### Other components

- **Mindustry players**
- **Discord users**
- **Discord platform**

## Connections

- Mindustry players → Login and register: authenticate
- Mindustry players → Account commands: invoke
- Login and register → Session service: login session
- Account commands → Account service: manage account
- Session service → Account service: lookup account
- Session service → SQL database: read and write
- Account service → SQL database: read and write
- Player data cache → Session service: load session
- Player data cache → Account service: load account
- Player data cache → Message service: subscribe updates
- Account service → Message service: broadcast updates
- Message service → SQL database: queue messages
- Mindustry players → Chat pipeline: send chat
- Chat bridge → Message service: exchange messages
- Mindustry bridge → Message service: subscribe messages
- Discord commands → Discord service: check permissions
- Discord users → Discord commands: invoke
- Discord service → Discord platform: connect and manage roles
- Stall monitoring → Webhook service: send alert