How nik9play/vk-music-bot works
Project Type & Purpose
• This is a TypeScript-based Node.js Discord bot whose sole purpose is to play music from VK (and optionally Yandex Music) on Discord voice channels. It uses a shard‐based architecture to scale across multiple Discord guilds, communicates with external Lavalink nodes for audio streaming, and exposes an internal API for shard management.
Main Components (map to file tree)
a. Entrypoint & Core Client
• src/client.ts: initializes the Discord.js client, logs in, and sets up event handlers.
b. Shard Management
• src/shardManager/manager.ts: spawns and supervises worker processes (one per shard).
• src/shardManager/api/server.ts: runs an HTTP server exposing management endpoints (health, metrics).
c. IPC Layer
• src/events/ipcManager.ts + src/events/ipc/*.ts: defines IPC channels (addLavalinkNode, setPresence, clearQueues, etc.) for control messages between the manager and shards.
d. Event & Interaction Handling
• src/events/eventHandler.ts: wires Discord events (message, ready, voiceStateUpdate) to the internal logic.
• src/interactions/: modular command, button, modal, and select‐menu handlers (organized under commands/, buttons/, modals/).
e. Player & Audio Streaming
• src/modules/shoukakuManager.ts: manages Shoukaku connections to Lavalink nodes.
• src/modules/playerManager.ts & src/modules/botPlayer.ts: orchestrate track queues, playback state, and voice‐channel connections.
f. Loaders (external music sources)
• src/loaders/VK/VKLoader.ts & src/loaders/YandexMusic/YandexMusicLoader.ts: fetch track URIs/metadata from VK and Yandex APIs.
g. Persistence & Configuration
• src/db.ts: database connection/configurations (if used for storing settings or state).
• src/modules/env.ts: environment variable loading.
h. Helpers & Utilities
• src/helpers/*.ts: shared routines for play, search, queue commands.
• src/utils.ts, src/logger.ts: logging and utility functions.
i. Scripts & Config
• Procfile, app.json: deployment configuration (e.g., Heroku).
• tsconfig.json, .eslintrc.json, .prettierrc.json: build and lint rules.
External Services
• Discord Gateway & REST API (bot interactions).
• Lavalink cluster (audio streaming servers).
• VK API & Yandex Music API (track metadata/endpoints).
Interactions & Data Flows
1) A user issues a slash command, button click, or modal submission in Discord.
2) Discord Gateway (WebSocket) → Shard Worker process → eventHandler → appropriate command/interaction module.
3) Command logic calls a Loader (VK/Yandex) → fetch track URI & metadata via HTTP REST.
4) playerManager invokes shoukakuManager → sends Play request over WebSocket/REST to Lavalink node.
5) Lavalink streams audio back to the voice channel (RTP/WebSocket).
6) Any cross‐shard control (e.g., global presence change, queue clear) travels via IPC channels to the Shard Manager or other shards.
7) Shard Manager API server can be called to add/remove Lavalink nodes or fetch clustersInfo.
Architectural Patterns & Principles
• Event-Driven: All Discord interactions and inter-process commands use event emitters and IPC messages.
• Modular Separation: Commands, buttons, modals, and loaders are isolated in their own directories for extensibility.
• Process Isolation: Each shard runs in its own Node.js process; the manager coordinates them.
• External Streaming Service: Lavalink handles heavy audio load, decoupled from bot logic.
• Configuration as Code: Environment variables and config files (Procfile, app.json) control deployment.
• Rectangles for Node.js components: Shard Manager, Shard Workers, IPC Manager, Database.
• Core Bot Logic (client.ts, modules): Blue
• Shard Orchestration (manager, IPC): Green
• External Services & APIs: Orange
• Helpers/Utilities: Grey
d. Component Grouping
• Src/interactions, src/events under “Event Handling Layer.”
• Src/modules/shoukakuManager & playerManager under “Audio Streaming Layer.”
• Src/loaders as subcomponents of the “Loader Layer.”