# lazaroagomez/beatdock architecture

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

- Interactive diagram: https://gitdiagram.com/lazaroagomez/beatdock
- Repository: https://github.com/lazaroagomez/beatdock

## Overview

BeatDock is a Discord music bot: users issue slash commands or interact with search/player controls, the bot validates requests and manages a Lavalink player and queue, then reports playback state in Discord. The graph preserves documented source support, autoplay, queue controls, filtering, lyrics, permissions, localization, and public-node fallback. Some subsystems are documented or indexed but not excerpted, so their internal links are omitted rather than inferred; optional external services are shown as integrations.

Main entry points: [`src/commands`](https://github.com/lazaroagomez/beatdock/tree/main/src/commands) (Slash commands), [`src/events/interactionCreate.js`](https://github.com/lazaroagomez/beatdock/blob/main/src/events/interactionCreate.js) (Interaction routing), [`src/utils/PlayerController.js`](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/PlayerController.js) (Player controller), [`src/interactions/searchNavigation.js`](https://github.com/lazaroagomez/beatdock/blob/main/src/interactions/searchNavigation.js) (Search navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Discord interaction"]
  node_commands["Slash commands"]
  node_interaction_router["Interaction routing"]
  node_search_ui["Search navigation"]
  node_filter_ui["Filter navigation"]
  node_permissions["Role permissions"]
  node_query_security["Query validation<br/>[queryGuard.js]"]
  node_search_session[("Search sessions<br/>[searchSessions.js]")]
end

subgraph group_playback["Playback experience"]
  node_queue_controls["Queue controls<br/>[PlayerActions.js]"]
  node_player_ui["Player controller"]
  node_playback_commands["Playback commands"]
  node_lyrics["Lyrics lookup<br/>[lyrics.js]"]
  node_embeds["Playback embeds<br/>[embeds.js]"]
  node_track_menu["Track selection<br/>[trackSelectMenu.js]"]
end

subgraph group_runtime["Player runtime"]
  node_autoplay["Autoplay<br/>[autoplay.js]"]
  node_lifecycle["Player lifecycle<br/>[playerLifecycle.js]"]
  node_failure_tracking["Playback resilience"]
  node_lavalink["Lavalink player"]
end

subgraph group_connections["Lavalink connectivity"]
  node_connection_manager["Connection manager"]
  node_public_nodes["Public node provider"]
end

subgraph group_support["Bot services"]
  node_language["Language manager<br/>[LanguageManager.js]"]
  node_event_handlers["Guild and voice events"]
  node_network_guard["Network safety<br/>[networkGuard.js]"]
  node_logger["Logging<br/>[logger.js]"]
end

node_discord_user(("Discord user"))
node_discord(("Discord platform"))
node_lavalink_nodes(("Lavalink nodes"))

node_discord_user -->|"submits interactions"| node_discord
node_discord -->|"routes interactions"| node_interaction_router
node_interaction_router -->|"dispatches commands"| node_commands
node_interaction_router -->|"dispatches selections"| node_search_ui
node_interaction_router -->|"dispatches filters"| node_filter_ui
node_interaction_router -->|"checks access"| node_permissions
node_commands -->|"validates queries"| node_query_security
node_commands -->|"stores results"| node_search_session
node_search_ui -->|"pages results"| node_search_session
node_search_ui -->|"adds selected track"| node_lavalink
node_search_ui -->|"updates player UI"| node_player_ui
node_commands -->|"searches and plays"| node_lavalink
node_playback_commands -.->|"controls playback"| node_lavalink
node_commands -->|"shuffles queue"| node_queue_controls
node_interaction_router -->|"handles player actions"| node_queue_controls
node_queue_controls -->|"builds track choices"| node_track_menu
node_player_ui -->|"formats playback"| node_embeds
node_player_ui -->|"truncates track text"| node_track_menu
node_lyrics -.->|"reads current track"| node_lavalink
node_lavalink -->|"requests recommendations"| node_autoplay
node_lavalink -->|"drives cleanup"| node_lifecycle
node_lavalink -->|"records playback outcomes"| node_failure_tracking
node_connection_manager -->|"connects and reconnects"| node_lavalink_nodes
node_connection_manager -->|"selects public node"| node_public_nodes
node_public_nodes -->|"fetches node list"| node_lavalink_nodes
node_lavalink -->|"streams tracks"| node_lavalink_nodes
node_query_security -->|"checks hosts"| node_network_guard
node_event_handlers -->|"cleans guild sessions"| node_search_session
node_event_handlers -->|"cleans player state"| node_lifecycle
node_discord -->|"displays player controls"| node_player_ui
node_commands -.->|"localizes replies"| node_language
node_player_ui -->|"localizes embeds"| node_language

click node_commands "https://github.com/lazaroagomez/beatdock/tree/main/src/commands"
click node_interaction_router "https://github.com/lazaroagomez/beatdock/blob/main/src/events/interactionCreate.js"
click node_search_ui "https://github.com/lazaroagomez/beatdock/blob/main/src/interactions/searchNavigation.js"
click node_filter_ui "https://github.com/lazaroagomez/beatdock/blob/main/src/interactions/filterNavigation.js"
click node_permissions "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/permissionChecker.js"
click node_query_security "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/queryGuard.js"
click node_search_session "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/searchSessions.js"
click node_queue_controls "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/PlayerActions.js"
click node_player_ui "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/PlayerController.js"
click node_playback_commands "https://github.com/lazaroagomez/beatdock/tree/main/src/commands"
click node_lyrics "https://github.com/lazaroagomez/beatdock/blob/main/src/commands/lyrics.js"
click node_embeds "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/embeds.js"
click node_track_menu "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/trackSelectMenu.js"
click node_autoplay "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/autoplay.js"
click node_lifecycle "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/playerLifecycle.js"
click node_failure_tracking "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/playbackFailureTracker.js"
click node_connection_manager "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/LavalinkConnectionManager.js"
click node_public_nodes "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/PublicNodeProvider.js"
click node_language "https://github.com/lazaroagomez/beatdock/blob/main/src/LanguageManager.js"
click node_event_handlers "https://github.com/lazaroagomez/beatdock/tree/main/src/events"
click node_network_guard "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/networkGuard.js"
click node_logger "https://github.com/lazaroagomez/beatdock/blob/main/src/utils/logger.js"

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_commands,node_interaction_router,node_search_ui,node_filter_ui,node_permissions,node_query_security,node_search_session,node_discord_user toneBlue
class node_queue_controls,node_player_ui,node_playback_commands,node_lyrics,node_embeds,node_track_menu toneAmber
class node_autoplay,node_lifecycle,node_failure_tracking,node_lavalink toneMint
class node_connection_manager,node_public_nodes toneRose
class node_language,node_event_handlers,node_network_guard,node_logger,node_discord,node_lavalink_nodes toneIndigo
```

## Components

### Discord interaction

- [Slash commands](https://github.com/lazaroagomez/beatdock/tree/main/src/commands): `src/commands`
- [Interaction routing](https://github.com/lazaroagomez/beatdock/blob/main/src/events/interactionCreate.js): `src/events/interactionCreate.js`
- [Search navigation](https://github.com/lazaroagomez/beatdock/blob/main/src/interactions/searchNavigation.js): `src/interactions/searchNavigation.js`
- [Filter navigation](https://github.com/lazaroagomez/beatdock/blob/main/src/interactions/filterNavigation.js): `src/interactions/filterNavigation.js`
- [Role permissions](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/permissionChecker.js): `src/utils/permissionChecker.js`
- [Query validation](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/queryGuard.js): `src/utils/queryGuard.js`
- [Search sessions](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/searchSessions.js): `src/utils/searchSessions.js`

### Playback experience

- [Queue controls](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/PlayerActions.js): `src/utils/PlayerActions.js`
- [Player controller](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/PlayerController.js): `src/utils/PlayerController.js`
- [Playback commands](https://github.com/lazaroagomez/beatdock/tree/main/src/commands): `src/commands`
- [Lyrics lookup](https://github.com/lazaroagomez/beatdock/blob/main/src/commands/lyrics.js): `src/commands/lyrics.js`
- [Playback embeds](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/embeds.js): `src/utils/embeds.js`
- [Track selection](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/trackSelectMenu.js): `src/utils/trackSelectMenu.js`

### Player runtime

- [Autoplay](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/autoplay.js): `src/utils/autoplay.js`
- [Player lifecycle](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/playerLifecycle.js): `src/utils/playerLifecycle.js`
- [Playback resilience](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/playbackFailureTracker.js): `src/utils/playbackFailureTracker.js`
- **Lavalink player**

### Lavalink connectivity

- [Connection manager](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/LavalinkConnectionManager.js): `src/utils/LavalinkConnectionManager.js`
- [Public node provider](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/PublicNodeProvider.js): `src/utils/PublicNodeProvider.js`

### Bot services

- [Language manager](https://github.com/lazaroagomez/beatdock/blob/main/src/LanguageManager.js): `src/LanguageManager.js`
- [Guild and voice events](https://github.com/lazaroagomez/beatdock/tree/main/src/events): `src/events`
- [Network safety](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/networkGuard.js): `src/utils/networkGuard.js`
- [Logging](https://github.com/lazaroagomez/beatdock/blob/main/src/utils/logger.js): `src/utils/logger.js`

### Other components

- **Discord user**
- **Discord platform**
- **Lavalink nodes**

## Connections

- Discord user → Discord platform: submits interactions (evidence: `README.md`)
- Discord platform → Interaction routing: routes interactions (evidence: `src/events/interactionCreate.js`)
- Interaction routing → Slash commands: dispatches commands (evidence: `src/events/interactionCreate.js`)
- Interaction routing → Search navigation: dispatches selections (evidence: `src/events/interactionCreate.js`)
- Interaction routing → Filter navigation: dispatches filters (evidence: `src/events/interactionCreate.js`)
- Interaction routing → Role permissions: checks access (evidence: `src/events/interactionCreate.js`)
- Slash commands → Query validation: validates queries (evidence: `src/commands/play.js`)
- Slash commands → Search sessions: stores results (evidence: `src/commands/search.js`)
- Search navigation → Search sessions: pages results (evidence: `src/interactions/searchNavigation.js`)
- Search navigation → Lavalink player: adds selected track (evidence: `src/interactions/searchNavigation.js`)
- Search navigation → Player controller: updates player UI (evidence: `src/interactions/searchNavigation.js`)
- Slash commands → Lavalink player: searches and plays (evidence: `src/commands/play.js`)
- Playback commands → Lavalink player: controls playback
- Slash commands → Queue controls: shuffles queue (evidence: `src/commands/shuffle.js`)
- Interaction routing → Queue controls: handles player actions (evidence: `src/events/interactionCreate.js`)
- Queue controls → Track selection: builds track choices (evidence: `src/utils/PlayerActions.js`)
- Player controller → Playback embeds: formats playback (evidence: `src/utils/PlayerController.js`)
- Player controller → Track selection: truncates track text (evidence: `src/utils/PlayerController.js`)
- Lyrics lookup → Lavalink player: reads current track
- Lavalink player → Autoplay: requests recommendations
- Lavalink player → Player lifecycle: drives cleanup
- Lavalink player → Playback resilience: records playback outcomes
- Connection manager → Lavalink nodes: connects and reconnects (evidence: `src/utils/LavalinkConnectionManager.js`)
- Connection manager → Public node provider: selects public node (evidence: `src/utils/LavalinkConnectionManager.js`)
- Public node provider → Lavalink nodes: fetches node list (evidence: `src/utils/PublicNodeProvider.js`)
- Lavalink player → Lavalink nodes: streams tracks (evidence: `README.md`)
- Query validation → Network safety: checks hosts (evidence: `src/utils/queryGuard.js`)
- Guild and voice events → Search sessions: cleans guild sessions (evidence: `src/events/guildDelete.js`)
- Guild and voice events → Player lifecycle: cleans player state (evidence: `src/events/guildDelete.js`)
- Discord platform → Player controller: displays player controls (evidence: `src/utils/PlayerController.js`)
- Slash commands → Language manager: localizes replies
- Player controller → Language manager: localizes embeds (evidence: `src/utils/PlayerController.js`)
