# softwmv/discord-music-bot architecture

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

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

## Overview

This self-hosted Discord music bot turns user slash commands into per-guild playback: the bot loads command cogs, music commands resolve tracks, and a GuildPlayer maintains an in-memory queue and drives voice playback. Configuration and guild settings are handled separately, with settings stored in SQLite. The README also documents utility and dice commands and auto-loaded command categories. The graph reflects the sampled source and documented capabilities; some command details and the music-to-settings persistence connection are not visible in the excerpts.

Main entry points: [`cogs/music.py`](https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py) (Music commands), [`bot.py`](https://github.com/softwmv/discord-music-bot/blob/main/bot.py) (Bot runtime), [`cogs/commands.py`](https://github.com/softwmv/discord-music-bot/blob/main/cogs/commands.py) (Utility commands), [`cogs/fun.py`](https://github.com/softwmv/discord-music-bot/blob/main/cogs/fun.py) (Dice commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_bot["Bot runtime<br/>[bot.py]"]
  node_cog_loader["Cog loader<br/>[bot.py]"]
end

subgraph group_music["Music playback"]
  node_music_cog["Music commands<br/>[music.py]"]
  node_guild_player["Guild player<br/>[music.py]"]
  node_track_resolver["Track resolver<br/>[music.py]"]
  node_audio_source["Audio transcoding<br/>[music.py]"]
end

subgraph group_commands["Other commands"]
  node_utility_cog["Utility commands<br/>[commands.py]"]
  node_fun_cog["Dice commands<br/>[fun.py]"]
end

subgraph group_persistence["Configuration and storage"]
  node_config["Environment config<br/>[config.py]"]
  node_database[("Guild settings DB<br/>[db.py]")]
end

node_discord_users(("Discord users"))
node_discord_platform["Discord platform"]
node_ytdlp["yt-dlp"]
node_discord_voice["Discord voice"]

node_discord_users -->|"invoke commands"| node_discord_platform
node_discord_platform -.->|"delivers events"| node_bot
node_bot -->|"loads settings"| node_config
node_bot -->|"connects and closes"| node_database
node_bot -->|"loads extensions"| node_cog_loader
node_cog_loader -->|"loads cog"| node_music_cog
node_cog_loader -->|"loads cog"| node_utility_cog
node_cog_loader -->|"loads cog"| node_fun_cog
node_discord_users -->|"request playback"| node_music_cog
node_music_cog -->|"gets player"| node_guild_player
node_music_cog -->|"resolves track"| node_track_resolver
node_track_resolver -->|"extracts stream"| node_ytdlp
node_guild_player -->|"creates source"| node_audio_source
node_audio_source -->|"plays audio"| node_discord_voice
node_music_cog -->|"joins and controls"| node_discord_voice
node_music_cog -.->|"persists settings"| node_database
node_discord_users -->|"request status"| node_utility_cog
node_discord_users -->|"roll dice"| node_fun_cog

click node_bot "https://github.com/softwmv/discord-music-bot/blob/main/bot.py"
click node_cog_loader "https://github.com/softwmv/discord-music-bot/blob/main/bot.py"
click node_config "https://github.com/softwmv/discord-music-bot/blob/main/config.py"
click node_database "https://github.com/softwmv/discord-music-bot/blob/main/db.py"
click node_music_cog "https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py"
click node_guild_player "https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py"
click node_track_resolver "https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py"
click node_audio_source "https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py"
click node_utility_cog "https://github.com/softwmv/discord-music-bot/blob/main/cogs/commands.py"
click node_fun_cog "https://github.com/softwmv/discord-music-bot/blob/main/cogs/fun.py"

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_bot,node_cog_loader,node_discord_users toneBlue
class node_music_cog,node_guild_player,node_track_resolver,node_audio_source toneAmber
class node_utility_cog,node_fun_cog toneMint
class node_config,node_database toneRose
class node_discord_platform,node_ytdlp,node_discord_voice toneIndigo
```

## Components

### Bot runtime

- [Bot runtime](https://github.com/softwmv/discord-music-bot/blob/main/bot.py): `bot.py`
- [Cog loader](https://github.com/softwmv/discord-music-bot/blob/main/bot.py): `bot.py`

### Music playback

- [Music commands](https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py): `cogs/music.py`
- [Guild player](https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py): `cogs/music.py`
- [Track resolver](https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py): `cogs/music.py`
- [Audio transcoding](https://github.com/softwmv/discord-music-bot/blob/main/cogs/music.py): `cogs/music.py`

### Other commands

- [Utility commands](https://github.com/softwmv/discord-music-bot/blob/main/cogs/commands.py): `cogs/commands.py`
- [Dice commands](https://github.com/softwmv/discord-music-bot/blob/main/cogs/fun.py): `cogs/fun.py`

### Configuration and storage

- [Environment config](https://github.com/softwmv/discord-music-bot/blob/main/config.py): `config.py`
- [Guild settings DB](https://github.com/softwmv/discord-music-bot/blob/main/db.py): `db.py`

### Other components

- **Discord users**
- **Discord platform**
- **yt-dlp**
- **Discord voice**

## Connections

- Discord users → Discord platform: invoke commands (evidence: `README.md`)
- Discord platform → Bot runtime: delivers events
- Bot runtime → Environment config: loads settings (evidence: `bot.py`)
- Bot runtime → Guild settings DB: connects and closes (evidence: `bot.py`)
- Bot runtime → Cog loader: loads extensions (evidence: `bot.py`)
- Cog loader → Music commands: loads cog (evidence: `README.md`)
- Cog loader → Utility commands: loads cog (evidence: `README.md`)
- Cog loader → Dice commands: loads cog (evidence: `README.md`)
- Discord users → Music commands: request playback (evidence: `README.md`)
- Music commands → Guild player: gets player (evidence: `cogs/music.py`)
- Music commands → Track resolver: resolves track (evidence: `cogs/music.py`)
- Track resolver → yt-dlp: extracts stream (evidence: `cogs/music.py`)
- Guild player → Audio transcoding: creates source (evidence: `cogs/music.py`)
- Audio transcoding → Discord voice: plays audio (evidence: `README.md`)
- Music commands → Discord voice: joins and controls (evidence: `cogs/music.py`)
- Music commands → Guild settings DB: persists settings
- Discord users → Utility commands: request status (evidence: `README.md`)
- Discord users → Dice commands: roll dice (evidence: `cogs/fun.py`)
