# ckagias/discord-bot architecture

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

- Interactive diagram: https://gitdiagram.com/ckagias/discord-bot
- Repository: https://github.com/ckagias/discord-bot

## Overview

This repository is a Discord community bot with a guild-management dashboard. Members interact through Discord commands, events, and components; administrators can also configure guild features in the dashboard. The bot covers moderation, community tools, leveling, economy, games, and music, with MongoDB-backed state and Lavalink playback. The map emphasizes documented product capabilities and sampled startup/event wiring; unsampled command and dashboard action internals are represented only at their supported directory paths, without speculative call edges.

Main entry points: [`src/index.ts`](https://github.com/ckagias/discord-bot/blob/main/src/index.ts) (Bot startup), [`handlers/lavalinkHandler.ts`](https://github.com/ckagias/discord-bot/blob/main/handlers/lavalinkHandler.ts) (Lavalink integration), [`events`](https://github.com/ckagias/discord-bot/tree/main/events) (Gateway events), [`models`](https://github.com/ckagias/discord-bot/tree/main/models) (Bot data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_startup["Bot startup<br/>[index.ts]"]
  node_event_loader["Event registration<br/>[eventHandler.ts]"]
  node_events["Gateway events"]
  node_command_loader["Command registration"]
  node_components["Interactive components"]
end

subgraph group_features["Guild features"]
  node_commands["Slash commands"]
  node_moderation["Moderation and safety"]
  node_community["Community tools"]
  node_leveling["XP and leveling"]
  node_economy_games["Economy and games"]
  node_music_commands["Music controls"]
end

subgraph group_state["Persistent state"]
  node_music_persistence["Music recovery"]
  node_bot_models[("Bot data models")]
  node_dashboard_models[("Dashboard data models")]
end

subgraph group_integrations["External services"]
  node_discord{{"Discord platform"}}
  node_music_runtime["Lavalink integration<br/>[lavalinkHandler.ts]"]
  node_mongo[("MongoDB")]
  node_discord_oauth{{"Discord OAuth API"}}
end

subgraph group_dashboard["Admin dashboard"]
  node_oauth["Dashboard authentication"]
  node_dashboard_pages["Guild settings pages"]
  node_dashboard_actions["Settings actions"]
end

node_member(("Discord members"))
node_dashboard_user(("Guild administrator"))

node_member -->|"uses"| node_discord
node_discord -->|"sends events"| node_events
node_startup -->|"connects"| node_mongo
node_startup -->|"registers events"| node_event_loader
node_startup -->|"registers commands"| node_command_loader
node_startup -->|"registers components"| node_components
node_event_loader -->|"loads listeners"| node_events
node_startup -->|"initializes"| node_music_runtime
node_music_runtime -->|"persists playback"| node_music_persistence
node_music_runtime -->|"sends playback updates"| node_discord
node_dashboard_user -->|"signs in"| node_oauth
node_oauth -->|"exchanges credentials"| node_discord_oauth
node_dashboard_user -->|"configures guild"| node_dashboard_pages
node_dashboard_pages -->|"submits settings"| node_dashboard_actions
node_commands -->|"uses persistent state"| node_bot_models
node_events -->|"uses persistent state"| node_bot_models
node_dashboard_actions -->|"uses data models"| node_dashboard_models
node_bot_models -->|"stores state"| node_mongo
node_dashboard_models -->|"stores dashboard data"| node_mongo

click node_startup "https://github.com/ckagias/discord-bot/blob/main/src/index.ts"
click node_event_loader "https://github.com/ckagias/discord-bot/blob/main/handlers/eventHandler.ts"
click node_events "https://github.com/ckagias/discord-bot/tree/main/events"
click node_command_loader "https://github.com/ckagias/discord-bot/blob/main/handlers/slashCommandHandler.ts"
click node_commands "https://github.com/ckagias/discord-bot/tree/main/slashCommands"
click node_components "https://github.com/ckagias/discord-bot/blob/main/handlers/componentHandler.ts"
click node_moderation "https://github.com/ckagias/discord-bot/tree/main/slashCommands/moderation"
click node_community "https://github.com/ckagias/discord-bot/tree/main/slashCommands/utility"
click node_leveling "https://github.com/ckagias/discord-bot/tree/main/slashCommands/leveling"
click node_economy_games "https://github.com/ckagias/discord-bot/tree/main/slashCommands/economy"
click node_music_commands "https://github.com/ckagias/discord-bot/tree/main/slashCommands/music"
click node_music_runtime "https://github.com/ckagias/discord-bot/blob/main/handlers/lavalinkHandler.ts"
click node_music_persistence "https://github.com/ckagias/discord-bot/blob/main/utils/musicPersistence.ts"
click node_bot_models "https://github.com/ckagias/discord-bot/tree/main/models"
click node_oauth "https://github.com/ckagias/discord-bot/tree/main/dashboard/app/api/auth"
click node_dashboard_pages "https://github.com/ckagias/discord-bot/tree/main/dashboard/app/dashboard/%5BguildId%5D"
click node_dashboard_actions "https://github.com/ckagias/discord-bot/tree/main/dashboard/app/dashboard/%5BguildId%5D"
click node_dashboard_models "https://github.com/ckagias/discord-bot/tree/main/dashboard/lib/models"

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_startup,node_event_loader,node_events,node_command_loader,node_components toneBlue
class node_commands,node_moderation,node_community,node_leveling,node_economy_games,node_music_commands toneAmber
class node_music_persistence,node_bot_models,node_dashboard_models toneMint
class node_discord,node_music_runtime,node_mongo,node_discord_oauth toneRose
class node_oauth,node_dashboard_pages,node_dashboard_actions,node_member,node_dashboard_user toneIndigo
```

## Components

### Bot runtime

- [Bot startup](https://github.com/ckagias/discord-bot/blob/main/src/index.ts): `src/index.ts`
- [Event registration](https://github.com/ckagias/discord-bot/blob/main/handlers/eventHandler.ts): `handlers/eventHandler.ts`
- [Gateway events](https://github.com/ckagias/discord-bot/tree/main/events): `events`
- [Command registration](https://github.com/ckagias/discord-bot/blob/main/handlers/slashCommandHandler.ts): `handlers/slashCommandHandler.ts`
- [Interactive components](https://github.com/ckagias/discord-bot/blob/main/handlers/componentHandler.ts): `handlers/componentHandler.ts`

### Guild features

- [Slash commands](https://github.com/ckagias/discord-bot/tree/main/slashCommands): `slashCommands`
- [Moderation and safety](https://github.com/ckagias/discord-bot/tree/main/slashCommands/moderation): `slashCommands/moderation`
- [Community tools](https://github.com/ckagias/discord-bot/tree/main/slashCommands/utility): `slashCommands/utility`
- [XP and leveling](https://github.com/ckagias/discord-bot/tree/main/slashCommands/leveling): `slashCommands/leveling`
- [Economy and games](https://github.com/ckagias/discord-bot/tree/main/slashCommands/economy): `slashCommands/economy`
- [Music controls](https://github.com/ckagias/discord-bot/tree/main/slashCommands/music): `slashCommands/music`

### Persistent state

- [Music recovery](https://github.com/ckagias/discord-bot/blob/main/utils/musicPersistence.ts): `utils/musicPersistence.ts`
- [Bot data models](https://github.com/ckagias/discord-bot/tree/main/models): `models`
- [Dashboard data models](https://github.com/ckagias/discord-bot/tree/main/dashboard/lib/models): `dashboard/lib/models`

### External services

- **Discord platform**
- [Lavalink integration](https://github.com/ckagias/discord-bot/blob/main/handlers/lavalinkHandler.ts): `handlers/lavalinkHandler.ts`
- **MongoDB**
- **Discord OAuth API**

### Admin dashboard

- [Dashboard authentication](https://github.com/ckagias/discord-bot/tree/main/dashboard/app/api/auth): `dashboard/app/api/auth`
- [Guild settings pages](https://github.com/ckagias/discord-bot/tree/main/dashboard/app/dashboard/%5BguildId%5D): `dashboard/app/dashboard/[guildId]`
- [Settings actions](https://github.com/ckagias/discord-bot/tree/main/dashboard/app/dashboard/%5BguildId%5D): `dashboard/app/dashboard/[guildId]`

### Other components

- **Discord members**
- **Guild administrator**

## Connections

- Discord members → Discord platform: uses
- Discord platform → Gateway events: sends events
- Bot startup → MongoDB: connects
- Bot startup → Event registration: registers events
- Bot startup → Command registration: registers commands
- Bot startup → Interactive components: registers components
- Event registration → Gateway events: loads listeners
- Bot startup → Lavalink integration: initializes
- Lavalink integration → Music recovery: persists playback
- Lavalink integration → Discord platform: sends playback updates
- Guild administrator → Dashboard authentication: signs in
- Dashboard authentication → Discord OAuth API: exchanges credentials
- Guild administrator → Guild settings pages: configures guild
- Guild settings pages → Settings actions: submits settings
- Slash commands → Bot data models: uses persistent state
- Gateway events → Bot data models: uses persistent state
- Settings actions → Dashboard data models: uses data models
- Bot data models → MongoDB: stores state
- Dashboard data models → MongoDB: stores dashboard data