# xdnw/locutus architecture

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

- Interactive diagram: https://gitdiagram.com/xdnw/locutus
- Repository: https://github.com/xdnw/locutus

## Overview

Locutus is a Discord bot for Politics and War, offering server administration and game-management tools through commands. The primary workflow is a Discord user invoking a command, which the command framework resolves and runs; commands can consult game data or call the Politics and War API and return a response. Separate capabilities include alliance role synchronization, war analysis, trade data, treaty-history ingestion and validation, and temporary conflict storage. README also documents MCP transport, but no corresponding implementation path appears in the supplied tree. Several subsystem connections are inferred only at the documented capability level; unsampled call wiring is omitted.

Main entry points: [`src/main/java/link/locutus/discord/commands/manager/CommandManager.java`](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/CommandManager.java) (Command manager), [`src/main/java/link/locutus/discord/apiv1/PoliticsAndWarBuilder.java`](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/apiv1/PoliticsAndWarBuilder.java) (Politics and War API), [`src/main/java/link/locutus/discord/commands/manager/v2/binding/bindings/PlaceholderEngine.java`](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/v2/binding/bindings/PlaceholderEngine.java) (Placeholder engine), [`src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeDailyIngestionService.java`](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeDailyIngestionService.java) (Treaty ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commanding["Command Runtime"]
  node_command_manager["Command manager"]
  node_placeholders["Placeholder engine"]
  node_runtime_lookup["Runtime lookup"]
  node_mcp["MCP transport"]
end

subgraph group_game["Game Data"]
  node_api_client["Politics and War API"]
  node_api_queries["API queries<br/>[Query.java]"]
end

subgraph group_operations["Alliance Operations"]
  node_account_commands["Account commands"]
  node_alliance_commands["Alliance commands<br/>[SetRank.java]"]
  node_bank_commands["Bank commands"]
  node_autorole["Auto-role service"]
end

subgraph group_analytics["Analysis Tools"]
  node_war_commands["War commands<br/>[SpyOpsService.java]"]
  node_war_ranking["War ranking"]
  node_trade_manager["Trade manager<br/>[TradeManager.java]"]
end

subgraph group_treaties["Treaty Data"]
  node_treaty_ingestion["Treaty ingestion"]
  node_treaty_validation["Treaty validation"]
  node_conflict_storage["Virtual conflict storage"]
  node_cloud_storage[("Cloud object storage")]
end

node_discord_user(("Discord user"))
node_game_service(("Politics and War"))
node_role_service(("Discord roles"))

node_discord_user -->|"invokes commands"| node_command_manager
node_command_manager -->|"binds command values"| node_placeholders
node_placeholders -->|"resolves game entities"| node_runtime_lookup
node_command_manager -->|"dispatches commands"| node_account_commands
node_command_manager -->|"dispatches commands"| node_alliance_commands
node_command_manager -->|"dispatches commands"| node_bank_commands
node_command_manager -->|"dispatches commands"| node_war_commands
node_command_manager -->|"dispatches commands"| node_war_ranking
node_command_manager -->|"dispatches commands"| node_trade_manager
node_autorole -->|"updates roles"| node_role_service
node_api_client -->|"executes queries"| node_api_queries
node_api_client -->|"requests game data"| node_game_service
node_treaty_ingestion -.->|"publishes artifacts"| node_cloud_storage
node_treaty_validation -->|"validates runtime state"| node_treaty_ingestion
node_conflict_storage -->|"reads and writes objects"| node_cloud_storage

click node_command_manager "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/CommandManager.java"
click node_placeholders "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/v2/binding/bindings/PlaceholderEngine.java"
click node_runtime_lookup "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/v2/impl/pw/filter/CommandRuntimeLookupService.java"
click node_account_commands "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/account/RegisterCommand.java"
click node_alliance_commands "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/alliance/SetRank.java"
click node_bank_commands "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/bank/TransferCommand.java"
click node_autorole "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/util/task/roles/AutoRoleService.java"
click node_war_commands "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/war/SpyOpsService.java"
click node_war_ranking "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/v2/impl/pw/ranking/WarRankingService.java"
click node_trade_manager "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/util/trade/TradeManager.java"
click node_api_client "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/apiv1/PoliticsAndWarBuilder.java"
click node_api_queries "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/apiv1/queries/Query.java"
click node_treaty_ingestion "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeDailyIngestionService.java"
click node_treaty_validation "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeValidationService.java"
click node_conflict_storage "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/db/conflict/VirtualConflictStorageManager.java"
click node_cloud_storage "https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/web/jooby/S3CompatibleStorage.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_command_manager,node_placeholders,node_runtime_lookup,node_mcp,node_discord_user toneBlue
class node_api_client,node_api_queries toneAmber
class node_account_commands,node_alliance_commands,node_bank_commands,node_autorole toneMint
class node_war_commands,node_war_ranking,node_trade_manager toneRose
class node_treaty_ingestion,node_treaty_validation,node_conflict_storage,node_cloud_storage,node_game_service,node_role_service toneIndigo
```

## Components

### Command Runtime

- [Command manager](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/CommandManager.java): `src/main/java/link/locutus/discord/commands/manager/CommandManager.java`
- [Placeholder engine](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/v2/binding/bindings/PlaceholderEngine.java): `src/main/java/link/locutus/discord/commands/manager/v2/binding/bindings/PlaceholderEngine.java`
- [Runtime lookup](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/v2/impl/pw/filter/CommandRuntimeLookupService.java): `src/main/java/link/locutus/discord/commands/manager/v2/impl/pw/filter/CommandRuntimeLookupService.java`
- **MCP transport**

### Game Data

- [Politics and War API](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/apiv1/PoliticsAndWarBuilder.java): `src/main/java/link/locutus/discord/apiv1/PoliticsAndWarBuilder.java`
- [API queries](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/apiv1/queries/Query.java): `src/main/java/link/locutus/discord/apiv1/queries/Query.java`

### Alliance Operations

- [Account commands](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/account/RegisterCommand.java): `src/main/java/link/locutus/discord/commands/account/RegisterCommand.java`
- [Alliance commands](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/alliance/SetRank.java): `src/main/java/link/locutus/discord/commands/alliance/SetRank.java`
- [Bank commands](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/bank/TransferCommand.java): `src/main/java/link/locutus/discord/commands/bank/TransferCommand.java`
- [Auto-role service](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/util/task/roles/AutoRoleService.java): `src/main/java/link/locutus/discord/util/task/roles/AutoRoleService.java`

### Analysis Tools

- [War commands](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/war/SpyOpsService.java): `src/main/java/link/locutus/discord/commands/war/SpyOpsService.java`
- [War ranking](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/commands/manager/v2/impl/pw/ranking/WarRankingService.java): `src/main/java/link/locutus/discord/commands/manager/v2/impl/pw/ranking/WarRankingService.java`
- [Trade manager](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/util/trade/TradeManager.java): `src/main/java/link/locutus/discord/util/trade/TradeManager.java`

### Treaty Data

- [Treaty ingestion](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeDailyIngestionService.java): `src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeDailyIngestionService.java`
- [Treaty validation](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeValidationService.java): `src/main/java/link/locutus/discord/treatyvis/runtime/TreatyVisRuntimeValidationService.java`
- [Virtual conflict storage](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/db/conflict/VirtualConflictStorageManager.java): `src/main/java/link/locutus/discord/db/conflict/VirtualConflictStorageManager.java`
- [Cloud object storage](https://github.com/xdnw/locutus/blob/master/src/main/java/link/locutus/discord/web/jooby/S3CompatibleStorage.java): `src/main/java/link/locutus/discord/web/jooby/S3CompatibleStorage.java`

### Other components

- **Discord user**
- **Politics and War**
- **Discord roles**

## Connections

- Discord user → Command manager: invokes commands
- Command manager → Placeholder engine: binds command values
- Placeholder engine → Runtime lookup: resolves game entities
- Command manager → Account commands: dispatches commands
- Command manager → Alliance commands: dispatches commands
- Command manager → Bank commands: dispatches commands
- Command manager → War commands: dispatches commands
- Command manager → War ranking: dispatches commands
- Command manager → Trade manager: dispatches commands
- Auto-role service → Discord roles: updates roles
- Politics and War API → API queries: executes queries
- Politics and War API → Politics and War: requests game data
- Treaty ingestion → Cloud object storage: publishes artifacts
- Treaty validation → Treaty ingestion: validates runtime state
- Virtual conflict storage → Cloud object storage: reads and writes objects