# chocomeow/vocard architecture

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

- Interactive diagram: https://gitdiagram.com/chocomeow/vocard
- Repository: https://github.com/chocomeow/vocard

## Overview

Vocard is a Discord music bot. A user issues a slash or message command, the bot loads and queues tracks through its Lavalink integration, then controls playback and presents it through Discord messages and interactive views. Separate capabilities include playlists, lyrics, sound effects, configurable settings, localization, and IPC. The source index supports several module dependencies, while excerpts confirm key player, node, storage, and controller behavior; unsampled subsystems are included where documented, with uncertain wiring omitted.

Main entry points: [`voicelink/player.py`](https://github.com/chocomeow/vocard/blob/main/voicelink/player.py) (Player session), [`cogs/basic.py`](https://github.com/chocomeow/vocard/blob/main/cogs/basic.py) (Music commands), [`main.py`](https://github.com/chocomeow/vocard/blob/main/main.py) (Bot application), [`voicelink/pool.py`](https://github.com/chocomeow/vocard/blob/main/voicelink/pool.py) (Lavalink node pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Discord bot"]
  node_application["Bot application<br/>[main.py]"]
  node_basic_commands["Music commands<br/>[basic.py]"]
  node_event_listeners["Event listeners<br/>[listeners.py]"]
  node_shared_helpers["Shared helpers<br/>[function.py]"]
  node_task_jobs["Background tasks<br/>[task.py]"]
end

subgraph group_playback["Music playback"]
  node_player["Player session<br/>[player.py]"]
  node_pool["Lavalink node pool<br/>[pool.py]"]
  node_queue["Track queue<br/>[queue.py]"]
  node_track_objects["Track objects<br/>[objects.py]"]
  node_filters["Audio filters<br/>[filters.py]"]
  node_track_loading["Track loading<br/>[pool.py]"]
end

subgraph group_features["Music features"]
  node_effect_commands["Sound effects<br/>[effect.py]"]
  node_settings_commands["Settings commands<br/>[settings.py]"]
  node_playlist_commands["Playlist commands<br/>[playlist.py]"]
  node_lyrics["Lyrics<br/>[lyrics.py]"]
end

subgraph group_experience["User experience"]
  node_language["Localization<br/>[language.py]"]
  node_controller["Playback controls<br/>[controller.py]"]
  node_other_views["Feature views"]
end

subgraph group_state["State and integration"]
  node_mongodb[("MongoDB state<br/>[mongodb.py]")]
  node_ipc["IPC client<br/>[client.py]"]
  node_configuration["Bot configuration<br/>[config.py]"]
end

node_discord_user(("Discord user"))
node_lavalink["Lavalink server"]

node_discord_user -->|"issues commands"| node_basic_commands
node_application -.->|"registers commands"| node_basic_commands
node_basic_commands -->|"controls playback"| node_player
node_basic_commands -->|"uses helpers"| node_shared_helpers
node_effect_commands -.->|"applies effects"| node_player
node_settings_commands -.->|"updates settings"| node_mongodb
node_playlist_commands -.->|"stores playlists"| node_mongodb
node_playlist_commands -->|"uses views"| node_other_views
node_player -->|"manages queue"| node_queue
node_player -->|"sends playback requests"| node_pool
node_pool -->|"loads and plays tracks"| node_lavalink
node_pool -->|"builds track results"| node_track_objects
node_player -->|"uses filters"| node_filters
node_player -->|"updates player state"| node_mongodb
node_player -->|"sends player events"| node_ipc
node_player -->|"updates controller"| node_controller
node_controller -->|"invokes controls"| node_player
node_player -->|"gets translations"| node_language
node_event_listeners -->|"handles player events"| node_player
node_other_views -.->|"presents lyrics"| node_lyrics
node_basic_commands -.->|"supports lyrics"| node_lyrics
node_application -.->|"loads configuration"| node_configuration
node_task_jobs -.->|"runs player tasks"| node_player
node_application -->|"uses helpers"| node_shared_helpers

click node_application "https://github.com/chocomeow/vocard/blob/main/main.py"
click node_basic_commands "https://github.com/chocomeow/vocard/blob/main/cogs/basic.py"
click node_effect_commands "https://github.com/chocomeow/vocard/blob/main/cogs/effect.py"
click node_settings_commands "https://github.com/chocomeow/vocard/blob/main/cogs/settings.py"
click node_event_listeners "https://github.com/chocomeow/vocard/blob/main/cogs/listeners.py"
click node_player "https://github.com/chocomeow/vocard/blob/main/voicelink/player.py"
click node_pool "https://github.com/chocomeow/vocard/blob/main/voicelink/pool.py"
click node_queue "https://github.com/chocomeow/vocard/blob/main/voicelink/queue.py"
click node_track_objects "https://github.com/chocomeow/vocard/blob/main/voicelink/objects.py"
click node_filters "https://github.com/chocomeow/vocard/blob/main/voicelink/filters.py"
click node_track_loading "https://github.com/chocomeow/vocard/blob/main/voicelink/pool.py"
click node_playlist_commands "https://github.com/chocomeow/vocard/blob/main/cogs/playlist.py"
click node_lyrics "https://github.com/chocomeow/vocard/blob/main/voicelink/lyrics.py"
click node_language "https://github.com/chocomeow/vocard/blob/main/voicelink/language.py"
click node_controller "https://github.com/chocomeow/vocard/blob/main/voicelink/views/controller.py"
click node_other_views "https://github.com/chocomeow/vocard/tree/main/voicelink/views"
click node_mongodb "https://github.com/chocomeow/vocard/blob/main/voicelink/mongodb.py"
click node_ipc "https://github.com/chocomeow/vocard/blob/main/voicelink/ipc/client.py"
click node_configuration "https://github.com/chocomeow/vocard/blob/main/voicelink/config.py"
click node_shared_helpers "https://github.com/chocomeow/vocard/blob/main/function.py"
click node_task_jobs "https://github.com/chocomeow/vocard/blob/main/cogs/task.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_application,node_basic_commands,node_event_listeners,node_shared_helpers,node_task_jobs,node_discord_user toneBlue
class node_player,node_pool,node_queue,node_track_objects,node_filters,node_track_loading toneAmber
class node_effect_commands,node_settings_commands,node_playlist_commands,node_lyrics,node_lavalink toneMint
class node_language,node_controller,node_other_views toneRose
class node_mongodb,node_ipc,node_configuration toneIndigo
```

## Components

### Discord bot

- [Bot application](https://github.com/chocomeow/vocard/blob/main/main.py): `main.py`
- [Music commands](https://github.com/chocomeow/vocard/blob/main/cogs/basic.py): `cogs/basic.py`
- [Event listeners](https://github.com/chocomeow/vocard/blob/main/cogs/listeners.py): `cogs/listeners.py`
- [Shared helpers](https://github.com/chocomeow/vocard/blob/main/function.py): `function.py`
- [Background tasks](https://github.com/chocomeow/vocard/blob/main/cogs/task.py): `cogs/task.py`

### Music playback

- [Player session](https://github.com/chocomeow/vocard/blob/main/voicelink/player.py): `voicelink/player.py`
- [Lavalink node pool](https://github.com/chocomeow/vocard/blob/main/voicelink/pool.py): `voicelink/pool.py`
- [Track queue](https://github.com/chocomeow/vocard/blob/main/voicelink/queue.py): `voicelink/queue.py`
- [Track objects](https://github.com/chocomeow/vocard/blob/main/voicelink/objects.py): `voicelink/objects.py`
- [Audio filters](https://github.com/chocomeow/vocard/blob/main/voicelink/filters.py): `voicelink/filters.py`
- [Track loading](https://github.com/chocomeow/vocard/blob/main/voicelink/pool.py): `voicelink/pool.py`

### Music features

- [Sound effects](https://github.com/chocomeow/vocard/blob/main/cogs/effect.py): `cogs/effect.py`
- [Settings commands](https://github.com/chocomeow/vocard/blob/main/cogs/settings.py): `cogs/settings.py`
- [Playlist commands](https://github.com/chocomeow/vocard/blob/main/cogs/playlist.py): `cogs/playlist.py`
- [Lyrics](https://github.com/chocomeow/vocard/blob/main/voicelink/lyrics.py): `voicelink/lyrics.py`

### User experience

- [Localization](https://github.com/chocomeow/vocard/blob/main/voicelink/language.py): `voicelink/language.py`
- [Playback controls](https://github.com/chocomeow/vocard/blob/main/voicelink/views/controller.py): `voicelink/views/controller.py`
- [Feature views](https://github.com/chocomeow/vocard/tree/main/voicelink/views): `voicelink/views`

### State and integration

- [MongoDB state](https://github.com/chocomeow/vocard/blob/main/voicelink/mongodb.py): `voicelink/mongodb.py`
- [IPC client](https://github.com/chocomeow/vocard/blob/main/voicelink/ipc/client.py): `voicelink/ipc/client.py`
- [Bot configuration](https://github.com/chocomeow/vocard/blob/main/voicelink/config.py): `voicelink/config.py`

### Other components

- **Discord user**
- **Lavalink server**

## Connections

- Discord user → Music commands: issues commands (evidence: `README.md`)
- Bot application → Music commands: registers commands
- Music commands → Player session: controls playback (evidence: `cogs/basic.py`)
- Music commands → Shared helpers: uses helpers (evidence: `cogs/basic.py`)
- Sound effects → Player session: applies effects
- Settings commands → MongoDB state: updates settings
- Playlist commands → MongoDB state: stores playlists
- Playlist commands → Feature views: uses views (evidence: `cogs/playlist.py`)
- Player session → Track queue: manages queue (evidence: `voicelink/player.py`)
- Player session → Lavalink node pool: sends playback requests (evidence: `voicelink/player.py`)
- Lavalink node pool → Lavalink server: loads and plays tracks (evidence: `voicelink/pool.py`)
- Lavalink node pool → Track objects: builds track results (evidence: `voicelink/pool.py`)
- Player session → Audio filters: uses filters (evidence: `voicelink/player.py`)
- Player session → MongoDB state: updates player state (evidence: `voicelink/player.py`)
- Player session → IPC client: sends player events (evidence: `voicelink/player.py`)
- Player session → Playback controls: updates controller (evidence: `voicelink/player.py`)
- Playback controls → Player session: invokes controls (evidence: `voicelink/views/controller.py`)
- Player session → Localization: gets translations (evidence: `voicelink/player.py`)
- Event listeners → Player session: handles player events (evidence: `cogs/listeners.py`)
- Feature views → Lyrics: presents lyrics
- Music commands → Lyrics: supports lyrics
- Bot application → Bot configuration: loads configuration
- Background tasks → Player session: runs player tasks
- Bot application → Shared helpers: uses helpers (evidence: `main.py`)