# danburen/velochatx architecture

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

- Interactive diagram: https://gitdiagram.com/danburen/velochatx
- Repository: https://github.com/danburen/velochatx

## Overview

VeloChatX is a Velocity proxy chat plugin for communication across backend servers. Its principal workflow handles player chat events, filters and formats messages, checks channel membership, and sends messages to eligible players; player join/server-switch events also trigger broadcasts and tab-list updates. The graph includes channel/server/player state, persistence, and documented capabilities such as timed broadcasts, localization, permissions, and tab-list customization. Some subsystems are represented from README statements or the source index; those sources do not establish every runtime connection.

Main entry points: [`src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java) (Event handling), [`src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java`](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java) (Shared proxy state), [`src/main/java/org/nitrowater/velochatx/manager/PlayerManager.java`](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/PlayerManager.java) (Player management), [`src/main/java/org/nitrowater/velochatx/domain/player/PlayerServiceImpl.java`](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/player/PlayerServiceImpl.java) (Player data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime events"]
  node_event_handler["Event handling"]
  node_game_events["Game events"]
  node_bootstrap["Plugin setup<br/>[VeloChatX.java]"]
  node_commands["Player commands"]
end

subgraph group_chat["Chat and channels"]
  node_chat_service["Chat formatting"]
  node_channel_service["Channel rules"]
  node_channel_model["Channel state<br/>[Channel.java]"]
  node_channel_manager["Channel and broadcasts"]
end

subgraph group_player["Players and servers"]
  node_server_service["Server registry"]
  node_server_state["Proxy server state<br/>[SubServer.java]"]
  node_player_service["Player data"]
  node_player_attribution["Player attribution"]
  node_player_mapper[("Player persistence<br/>[PlayerMapper.java]")]
  node_basic_methods["Shared proxy state<br/>[BasicMethods.java]"]
  node_player_manager["Player management<br/>[PlayerManager.java]"]
end

subgraph group_features["Additional features"]
  node_broadcast_service["Broadcasts"]
  node_tablist_service["Tab-list updates"]
  node_tablist_task["Tab-list task"]
  node_integrations["Documented integrations"]
end

node_players(("Players"))

node_event_handler -->|"filters and formats"| node_chat_service
node_event_handler -->|"checks channels"| node_channel_service
node_event_handler -->|"looks up players"| node_player_service
node_event_handler -->|"reads server"| node_server_service
node_event_handler -->|"broadcasts joins"| node_broadcast_service
node_event_handler -->|"queues updates"| node_tablist_service
node_tablist_service -->|"processes tasks"| node_tablist_task
node_channel_manager -->|"loads configuration"| node_bootstrap
node_basic_methods -->|"initializes"| node_channel_manager
node_basic_methods -->|"initializes"| node_player_manager
node_basic_methods -->|"creates state"| node_server_state
node_player_manager -->|"persists player data"| node_player_mapper
node_player_manager -->|"reads attribution"| node_player_attribution
node_player_service -->|"delegates persistence"| node_player_mapper
node_server_state -->|"tracks membership"| node_channel_model
node_players -.->|"trigger events"| node_event_handler
node_integrations -.->|"permissions and filtering"| node_chat_service
node_integrations -.->|"timed broadcasts"| node_broadcast_service
node_integrations -.->|"customizes tab list"| node_tablist_service
node_integrations -.->|"localization and language"| node_player_service

click node_event_handler "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java"
click node_game_events "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/event/VeloChatXGameEventHandler.java"
click node_chat_service "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/chat/ChatServiceImpl.java"
click node_channel_service "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/channel/ChannelServiceImpl.java"
click node_channel_model "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/entity/Channel.java"
click node_server_service "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/server/ServerServiceImpl.java"
click node_server_state "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/utils/SubServer.java"
click node_player_service "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/player/PlayerServiceImpl.java"
click node_player_attribution "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/utils/PlayerAttribution.java"
click node_player_mapper "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/mapper/PlayerMapper.java"
click node_bootstrap "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/VeloChatX.java"
click node_basic_methods "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java"
click node_channel_manager "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/ChannelManager.java"
click node_player_manager "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/PlayerManager.java"
click node_commands "https://github.com/danburen/velochatx/tree/main/src/main/java/org/nitrowater/velochatx/commands"
click node_broadcast_service "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/broadcast/BroadcastServiceImpl.java"
click node_tablist_service "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/tablist/TabListServiceImpl.java"
click node_tablist_task "https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/tablist/TabListUpdateTask.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_event_handler,node_game_events,node_bootstrap,node_commands toneBlue
class node_chat_service,node_channel_service,node_channel_model,node_channel_manager toneAmber
class node_server_service,node_server_state,node_player_service,node_player_attribution,node_player_mapper,node_basic_methods,node_player_manager toneMint
class node_broadcast_service,node_tablist_service,node_tablist_task,node_integrations toneRose
class node_players toneIndigo
```

## Components

### Runtime events

- [Event handling](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java): `src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`
- [Game events](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/event/VeloChatXGameEventHandler.java): `src/main/java/org/nitrowater/velochatx/domain/event/VeloChatXGameEventHandler.java`
- [Plugin setup](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/VeloChatX.java): `src/main/java/org/nitrowater/velochatx/VeloChatX.java`
- [Player commands](https://github.com/danburen/velochatx/tree/main/src/main/java/org/nitrowater/velochatx/commands): `src/main/java/org/nitrowater/velochatx/commands`

### Chat and channels

- [Chat formatting](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/chat/ChatServiceImpl.java): `src/main/java/org/nitrowater/velochatx/domain/chat/ChatServiceImpl.java`
- [Channel rules](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/channel/ChannelServiceImpl.java): `src/main/java/org/nitrowater/velochatx/domain/channel/ChannelServiceImpl.java`
- [Channel state](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/entity/Channel.java): `src/main/java/org/nitrowater/velochatx/entity/Channel.java`
- [Channel and broadcasts](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/ChannelManager.java): `src/main/java/org/nitrowater/velochatx/manager/ChannelManager.java`

### Players and servers

- [Server registry](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/server/ServerServiceImpl.java): `src/main/java/org/nitrowater/velochatx/domain/server/ServerServiceImpl.java`
- [Proxy server state](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/utils/SubServer.java): `src/main/java/org/nitrowater/velochatx/utils/SubServer.java`
- [Player data](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/player/PlayerServiceImpl.java): `src/main/java/org/nitrowater/velochatx/domain/player/PlayerServiceImpl.java`
- [Player attribution](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/utils/PlayerAttribution.java): `src/main/java/org/nitrowater/velochatx/utils/PlayerAttribution.java`
- [Player persistence](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/mapper/PlayerMapper.java): `src/main/java/org/nitrowater/velochatx/mapper/PlayerMapper.java`
- [Shared proxy state](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java): `src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java`
- [Player management](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/manager/PlayerManager.java): `src/main/java/org/nitrowater/velochatx/manager/PlayerManager.java`

### Additional features

- [Broadcasts](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/broadcast/BroadcastServiceImpl.java): `src/main/java/org/nitrowater/velochatx/domain/broadcast/BroadcastServiceImpl.java`
- [Tab-list updates](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/tablist/TabListServiceImpl.java): `src/main/java/org/nitrowater/velochatx/domain/tablist/TabListServiceImpl.java`
- [Tab-list task](https://github.com/danburen/velochatx/blob/main/src/main/java/org/nitrowater/velochatx/domain/tablist/TabListUpdateTask.java): `src/main/java/org/nitrowater/velochatx/domain/tablist/TabListUpdateTask.java`
- **Documented integrations**

### Other components

- **Players**

## Connections

- Event handling → Chat formatting: filters and formats (evidence: `src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`)
- Event handling → Channel rules: checks channels (evidence: `src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`)
- Event handling → Player data: looks up players (evidence: `src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`)
- Event handling → Server registry: reads server (evidence: `src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`)
- Event handling → Broadcasts: broadcasts joins (evidence: `src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`)
- Event handling → Tab-list updates: queues updates (evidence: `src/main/java/org/nitrowater/velochatx/domain/event/handler/VCXEventHandler.java`)
- Tab-list updates → Tab-list task: processes tasks (evidence: `src/main/java/org/nitrowater/velochatx/domain/tablist/TabListServiceImpl.java`)
- Channel and broadcasts → Plugin setup: loads configuration (evidence: `src/main/java/org/nitrowater/velochatx/manager/ChannelManager.java`)
- Shared proxy state → Channel and broadcasts: initializes (evidence: `src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java`)
- Shared proxy state → Player management: initializes (evidence: `src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java`)
- Shared proxy state → Proxy server state: creates state (evidence: `src/main/java/org/nitrowater/velochatx/manager/BasicMethods.java`)
- Player management → Player persistence: persists player data (evidence: `src/main/java/org/nitrowater/velochatx/manager/PlayerManager.java`)
- Player management → Player attribution: reads attribution (evidence: `src/main/java/org/nitrowater/velochatx/manager/PlayerManager.java`)
- Player data → Player persistence: delegates persistence (evidence: `src/main/java/org/nitrowater/velochatx/domain/player/PlayerServiceImpl.java`)
- Proxy server state → Channel state: tracks membership (evidence: `src/main/java/org/nitrowater/velochatx/utils/SubServer.java`)
- Players → Event handling: trigger events
- Documented integrations → Chat formatting: permissions and filtering
- Documented integrations → Broadcasts: timed broadcasts
- Documented integrations → Tab-list updates: customizes tab list
- Documented integrations → Player data: localization and language
