# umutxyp/musicbot architecture

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

- Interactive diagram: https://gitdiagram.com/umutxyp/musicbot
- Repository: https://github.com/umutxyp/musicbot

## Overview

Beatra is a Discord music bot: users issue slash commands or use playback controls; the bot resolves tracks and playlists through music providers, queues and plays audio in a voice channel, and updates localized embeds. The graph also preserves lyrics, autoplay, persistent guild language and player state, and playback recovery. Edges follow the shown imports and calls or documented capabilities; unsampled implementation details are represented only where the README documents them.

Main entry points: [`src/MusicPlayer.js`](https://github.com/umutxyp/musicbot/blob/main/src/MusicPlayer.js) (Music player), [`commands/play.js`](https://github.com/umutxyp/musicbot/blob/main/commands/play.js) (Play command), [`src/LanguageManager.js`](https://github.com/umutxyp/musicbot/blob/main/src/LanguageManager.js) (Language manager), [`index.js`](https://github.com/umutxyp/musicbot/blob/main/index.js) (Bot bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord_ux["Discord experience"]
  node_bootstrap["Bot bootstrap<br/>[index.js]"]
  node_loader["Command loader<br/>[commandLoader.js]"]
  node_play["Play command<br/>[play.js]"]
  node_search["Search command<br/>[search.js]"]
  node_nowplaying["Now Playing command<br/>[nowplaying.js]"]
  node_language_command["Language command<br/>[language.js]"]
  node_help["Help command<br/>[help.js]"]
  node_buttons["Button controls<br/>[buttonHandler.js]"]
  node_modals["Modal controls<br/>[modalHandler.js]"]
end

subgraph group_playback["Playback engine"]
  node_player["Music player<br/>[MusicPlayer.js]"]
  node_embeds["Playback embeds"]
  node_lyrics["Lyrics manager<br/>[LyricsManager.js]"]
end

subgraph group_sources["Music sources"]
  node_youtube["YouTube provider<br/>[YouTube.js]"]
  node_spotify["Spotify provider<br/>[Spotify.js]"]
  node_soundcloud["SoundCloud provider<br/>[SoundCloud.js]"]
  node_directlink["Direct-link provider<br/>[DirectLink.js]"]
end

subgraph group_support["State and localization"]
  node_language["Language manager<br/>[LanguageManager.js]"]
  node_playerstate["Player state"]
  node_errors["Error handler<br/>[ErrorHandler.js]"]
  node_config["Bot configuration<br/>[config.js]"]
end

node_listener(("Discord user"))
node_discord(("Discord"))
node_genius(("Genius lyrics"))
node_lrclib(("LRCLIB lyrics"))
node_language_db[("Guild language JSON<br/>[languages.json]")]
node_state_file[("Player state JSON<br/>[playerState.json]")]
node_audio_cache[("Local audio cache")]

node_listener -->|"issues commands"| node_discord
node_discord -->|"delivers interactions"| node_bootstrap
node_bootstrap -->|"loads commands"| node_loader
node_bootstrap -->|"restores state"| node_playerstate
node_bootstrap -->|"wires players"| node_player
node_bootstrap -->|"wires embeds"| node_embeds
node_loader -->|"registers command"| node_play
node_play -->|"queues tracks"| node_player
node_play -->|"updates playback UI"| node_embeds
node_play -->|"resolves tracks"| node_youtube
node_play -->|"resolves tracks"| node_spotify
node_play -->|"resolves tracks"| node_soundcloud
node_play -->|"resolves links"| node_directlink
node_play -->|"gets translations"| node_language
node_play -->|"formats errors"| node_errors
node_search -->|"searches tracks"| node_youtube
node_search -->|"gets translations"| node_language
node_nowplaying -->|"gets translations"| node_language
node_language_command -->|"sets guild language"| node_language
node_help -->|"gets translations"| node_language
node_buttons -->|"controls playback"| node_player
node_buttons -->|"refreshes embeds"| node_embeds
node_buttons -->|"requests lyrics"| node_lyrics
node_buttons -->|"gets translations"| node_language
node_modals -->|"gets translations"| node_language
node_player -->|"downloads audio"| node_youtube
node_player -->|"resolves equivalents"| node_spotify
node_player -->|"resolves equivalents"| node_soundcloud
node_player -.->|"gets stream info"| node_directlink
node_player -->|"persists playback"| node_playerstate
node_player -.->|"updates now playing"| node_embeds
node_player -->|"caches downloads"| node_audio_cache
node_embeds -->|"gets translations"| node_language
node_lyrics -->|"searches lyrics"| node_genius
node_lyrics -->|"fallback search"| node_lrclib
node_lyrics -->|"reads credentials"| node_config
node_language -->|"reads and writes"| node_language_db
node_playerstate -->|"reads and writes"| node_state_file
node_errors -->|"gets translations"| node_language
node_bootstrap -->|"connects bot"| node_discord
node_bootstrap -->|"reads settings"| node_config

click node_bootstrap "https://github.com/umutxyp/musicbot/blob/main/index.js"
click node_loader "https://github.com/umutxyp/musicbot/blob/main/src/commandLoader.js"
click node_play "https://github.com/umutxyp/musicbot/blob/main/commands/play.js"
click node_search "https://github.com/umutxyp/musicbot/blob/main/commands/search.js"
click node_nowplaying "https://github.com/umutxyp/musicbot/blob/main/commands/nowplaying.js"
click node_language_command "https://github.com/umutxyp/musicbot/blob/main/commands/language.js"
click node_help "https://github.com/umutxyp/musicbot/blob/main/commands/help.js"
click node_buttons "https://github.com/umutxyp/musicbot/blob/main/events/buttonHandler.js"
click node_modals "https://github.com/umutxyp/musicbot/blob/main/events/modalHandler.js"
click node_player "https://github.com/umutxyp/musicbot/blob/main/src/MusicPlayer.js"
click node_embeds "https://github.com/umutxyp/musicbot/blob/main/src/MusicEmbedManager.js"
click node_lyrics "https://github.com/umutxyp/musicbot/blob/main/src/LyricsManager.js"
click node_youtube "https://github.com/umutxyp/musicbot/blob/main/src/YouTube.js"
click node_spotify "https://github.com/umutxyp/musicbot/blob/main/src/Spotify.js"
click node_soundcloud "https://github.com/umutxyp/musicbot/blob/main/src/SoundCloud.js"
click node_directlink "https://github.com/umutxyp/musicbot/blob/main/src/DirectLink.js"
click node_language "https://github.com/umutxyp/musicbot/blob/main/src/LanguageManager.js"
click node_playerstate "https://github.com/umutxyp/musicbot/blob/main/src/PlayerStateManager.js"
click node_errors "https://github.com/umutxyp/musicbot/blob/main/src/ErrorHandler.js"
click node_config "https://github.com/umutxyp/musicbot/blob/main/config.js"
click node_language_db "https://github.com/umutxyp/musicbot/blob/main/database/languages.json"
click node_state_file "https://github.com/umutxyp/musicbot/blob/main/database/playerState.json"

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_bootstrap,node_loader,node_play,node_search,node_nowplaying,node_language_command,node_help,node_buttons,node_modals,node_listener toneBlue
class node_player,node_embeds,node_lyrics,node_language_db,node_state_file,node_audio_cache toneAmber
class node_youtube,node_spotify,node_soundcloud,node_directlink toneMint
class node_language,node_playerstate,node_errors,node_config toneRose
class node_discord,node_genius,node_lrclib toneIndigo
```

## Components

### Discord experience

- [Bot bootstrap](https://github.com/umutxyp/musicbot/blob/main/index.js): `index.js`
- [Command loader](https://github.com/umutxyp/musicbot/blob/main/src/commandLoader.js): `src/commandLoader.js`
- [Play command](https://github.com/umutxyp/musicbot/blob/main/commands/play.js): `commands/play.js`
- [Search command](https://github.com/umutxyp/musicbot/blob/main/commands/search.js): `commands/search.js`
- [Now Playing command](https://github.com/umutxyp/musicbot/blob/main/commands/nowplaying.js): `commands/nowplaying.js`
- [Language command](https://github.com/umutxyp/musicbot/blob/main/commands/language.js): `commands/language.js`
- [Help command](https://github.com/umutxyp/musicbot/blob/main/commands/help.js): `commands/help.js`
- [Button controls](https://github.com/umutxyp/musicbot/blob/main/events/buttonHandler.js): `events/buttonHandler.js`
- [Modal controls](https://github.com/umutxyp/musicbot/blob/main/events/modalHandler.js): `events/modalHandler.js`

### Playback engine

- [Music player](https://github.com/umutxyp/musicbot/blob/main/src/MusicPlayer.js): `src/MusicPlayer.js`
- [Playback embeds](https://github.com/umutxyp/musicbot/blob/main/src/MusicEmbedManager.js): `src/MusicEmbedManager.js`
- [Lyrics manager](https://github.com/umutxyp/musicbot/blob/main/src/LyricsManager.js): `src/LyricsManager.js`

### Music sources

- [YouTube provider](https://github.com/umutxyp/musicbot/blob/main/src/YouTube.js): `src/YouTube.js`
- [Spotify provider](https://github.com/umutxyp/musicbot/blob/main/src/Spotify.js): `src/Spotify.js`
- [SoundCloud provider](https://github.com/umutxyp/musicbot/blob/main/src/SoundCloud.js): `src/SoundCloud.js`
- [Direct-link provider](https://github.com/umutxyp/musicbot/blob/main/src/DirectLink.js): `src/DirectLink.js`

### State and localization

- [Language manager](https://github.com/umutxyp/musicbot/blob/main/src/LanguageManager.js): `src/LanguageManager.js`
- [Player state](https://github.com/umutxyp/musicbot/blob/main/src/PlayerStateManager.js): `src/PlayerStateManager.js`
- [Error handler](https://github.com/umutxyp/musicbot/blob/main/src/ErrorHandler.js): `src/ErrorHandler.js`
- [Bot configuration](https://github.com/umutxyp/musicbot/blob/main/config.js): `config.js`

### Other components

- **Discord user**
- **Discord**
- **Genius lyrics**
- **LRCLIB lyrics**
- [Guild language JSON](https://github.com/umutxyp/musicbot/blob/main/database/languages.json): `database/languages.json`
- [Player state JSON](https://github.com/umutxyp/musicbot/blob/main/database/playerState.json): `database/playerState.json`
- **Local audio cache**

## Connections

- Discord user → Discord: issues commands (evidence: `README.md`)
- Discord → Bot bootstrap: delivers interactions (evidence: `index.js`)
- Bot bootstrap → Command loader: loads commands (evidence: `index.js`)
- Bot bootstrap → Player state: restores state (evidence: `index.js`)
- Bot bootstrap → Music player: wires players (evidence: `index.js`)
- Bot bootstrap → Playback embeds: wires embeds (evidence: `index.js`)
- Command loader → Play command: registers command (evidence: `src/commandLoader.js`)
- Play command → Music player: queues tracks (evidence: `commands/play.js`)
- Play command → Playback embeds: updates playback UI (evidence: `commands/play.js`)
- Play command → YouTube provider: resolves tracks (evidence: `commands/play.js`)
- Play command → Spotify provider: resolves tracks (evidence: `commands/play.js`)
- Play command → SoundCloud provider: resolves tracks (evidence: `commands/play.js`)
- Play command → Direct-link provider: resolves links (evidence: `commands/play.js`)
- Play command → Language manager: gets translations (evidence: `commands/play.js`)
- Play command → Error handler: formats errors (evidence: `commands/play.js`)
- Search command → YouTube provider: searches tracks (evidence: `commands/search.js`)
- Search command → Language manager: gets translations (evidence: `commands/search.js`)
- Now Playing command → Language manager: gets translations (evidence: `commands/nowplaying.js`)
- Language command → Language manager: sets guild language (evidence: `commands/language.js`)
- Help command → Language manager: gets translations (evidence: `commands/help.js`)
- Button controls → Music player: controls playback (evidence: `events/buttonHandler.js`)
- Button controls → Playback embeds: refreshes embeds (evidence: `events/buttonHandler.js`)
- Button controls → Lyrics manager: requests lyrics (evidence: `events/buttonHandler.js`)
- Button controls → Language manager: gets translations (evidence: `events/buttonHandler.js`)
- Modal controls → Language manager: gets translations (evidence: `events/modalHandler.js`)
- Music player → YouTube provider: downloads audio (evidence: `src/MusicPlayer.js`)
- Music player → Spotify provider: resolves equivalents (evidence: `src/MusicPlayer.js`)
- Music player → SoundCloud provider: resolves equivalents (evidence: `src/MusicPlayer.js`)
- Music player → Direct-link provider: gets stream info (evidence: `src/MusicPlayer.js`)
- Music player → Player state: persists playback (evidence: `src/MusicPlayer.js`)
- Music player → Playback embeds: updates now playing (evidence: `src/MusicPlayer.js`)
- Music player → Local audio cache: caches downloads (evidence: `README.md`)
- Playback embeds → Language manager: gets translations (evidence: `src/MusicEmbedManager.js`)
- Lyrics manager → Genius lyrics: searches lyrics (evidence: `src/LyricsManager.js`)
- Lyrics manager → LRCLIB lyrics: fallback search (evidence: `src/LyricsManager.js`)
- Lyrics manager → Bot configuration: reads credentials (evidence: `src/LyricsManager.js`)
- Language manager → Guild language JSON: reads and writes (evidence: `src/LanguageManager.js`)
- Player state → Player state JSON: reads and writes (evidence: `src/PlayerStateManager.js`)
- Error handler → Language manager: gets translations (evidence: `src/ErrorHandler.js`)
- Bot bootstrap → Discord: connects bot (evidence: `index.js`)
- Bot bootstrap → Bot configuration: reads settings (evidence: `index.js`)
