# nik9play/vk-music-bot architecture

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

- Interactive diagram: https://gitdiagram.com/nik9play/vk-music-bot
- Repository: https://github.com/nik9play/vk-music-bot

## Overview

##### 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.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        DAPI["Discord API"] 
        LAVAL["Lavalink Cluster"]
        VKAPI["VK API"]
        YMAPI["Yandex Music API"]
    end

    %% Shard Orchestration Layer
    subgraph "Shard Orchestration Layer"
        SM["Shard Manager"]
        APIS["API Server"]
        IPCM["IPC Manager"]
        subgraph "IPC Channels"
            ALN["addLavalinkNode"]
            CLR["clearQueues"]
            CID["clientId"]
            CLINFO["clustersInfo"]
            DEST["destroyAll"]
            GETN["getLavalinkNodes"]
            RLN["removeLavalinkNode"]
            SP["setPresence"]
        end
    end

    %% Shard Worker
    subgraph "Shard Worker (×N)"
        C["Client"]
        EV["Event Handler"]
        subgraph "Interaction Handlers"
            BIM["Base Interaction Manager"]
            COMI["Command Interactions"]
            BUTI["Button Interactions"]
            MODI["Modal Interactions"]
            SELI["Select-Menu Interactions"]
            subgraph "Interaction Modules"
                CMDM["commands/*.ts"]
                BUTM["buttons/*.ts"]
                MODM["modals/*.ts"]
            end
        end
        subgraph "Audio Streaming Layer"
            SHM["Shoukaku Manager"]
            PM["Player Manager"]
            BP["Bot Player"]
        end
        subgraph "Loader Layer"
            VKL["VK Loader"]
            VKT["VK Types"]
            YML["YandexMusic Loader"]
            BL["Base Loader"]
        end
    end

    %% Persistence & Config
    subgraph "Persistence & Configuration"
        DB["Database"]
        ENV["Env Loader"]
        HELP["Helpers"]
        UTIL["Utils"]
        LOG["Logger"]
        subgraph "Config Files"
            PF["Procfile"]
            AJ["app.json"]
            TSC["tsconfig.json"]
            ESL[".eslintrc.json"]
            PRE[".prettierrc.json"]
        end
    end

    %% Connections
    DAPI -->|"WebSocket"| C
    C -->|"handles events"| EV
    EV -->|"routes to"| COMI
    COMI -->|"calls loader"| VKL
    COMI -->|"calls loader"| YML
    VKL -->|"HTTP REST"| VKAPI
    YML -->|"HTTP REST"| YMAPI
    BP -->|"orchestrated by"| PM
    PM -->|"uses"| SHM
    SHM -->|"WebSocket/REST"| LAVAL
    SM -->|"IPC"| C
    C -->|"IPC"| SM

    %% Click Events
    click C "https://github.com/nik9play/vk-music-bot/blob/next/src/client.ts"
    click SM "https://github.com/nik9play/vk-music-bot/blob/next/src/shardManager/manager.ts"
    click APIS "https://github.com/nik9play/vk-music-bot/blob/next/src/shardManager/api/server.ts"
    click IPCM "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipcManager.ts"
    click ALN "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/addLavalinkNode.ts"
    click CLR "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/clearQueues.ts"
    click CID "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/clientId.ts"
    click CLINFO "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/clustersInfo.ts"
    click DEST "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/destroyAll.ts"
    click GETN "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/getLavalinkNodes.ts"
    click RLN "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/removeLavalinkNode.ts"
    click SP "https://github.com/nik9play/vk-music-bot/blob/next/src/events/ipc/setPresence.ts"
    click EV "https://github.com/nik9play/vk-music-bot/blob/next/src/modules/eventHandler.ts"
    click BIM "https://github.com/nik9play/vk-music-bot/blob/next/src/interactions/baseInteractionManager.ts"
    click COMI "https://github.com/nik9play/vk-music-bot/blob/next/src/interactions/commandInteractions.ts"
    click BUTI "https://github.com/nik9play/vk-music-bot/blob/next/src/interactions/buttonInteractions.ts"
    click MODI "https://github.com/nik9play/vk-music-bot/blob/next/src/interactions/modalInteractions.ts"
    click SELI "https://github.com/nik9play/vk-music-bot/blob/next/src/interactions/selectMenuInteractions.ts"
    click CMDM "https://github.com/nik9play/vk-music-bot/tree/next/src/interactions/commands"
    click BUTM "https://github.com/nik9play/vk-music-bot/tree/next/src/interactions/buttons"
    click MODM "https://github.com/nik9play/vk-music-bot/tree/next/src/interactions/modals"
    click SHM "https://github.com/nik9play/vk-music-bot/blob/next/src/modules/shoukakuManager.ts"
    click PM "https://github.com/nik9play/vk-music-bot/blob/next/src/modules/playerManager.ts"
    click BP "https://github.com/nik9play/vk-music-bot/blob/next/src/modules/botPlayer.ts"
    click VKL "https://github.com/nik9play/vk-music-bot/blob/next/src/loaders/VK/VKLoader.ts"
    click VKT "https://github.com/nik9play/vk-music-bot/blob/next/src/loaders/VK/VKTypes.ts"
    click YML "https://github.com/nik9play/vk-music-bot/blob/next/src/loaders/YandexMusic/YandexMusicLoader.ts"
    click BL "https://github.com/nik9play/vk-music-bot/blob/next/src/loaders/baseLoader.ts"
    click DB "https://github.com/nik9play/vk-music-bot/blob/next/src/db.ts"
    click ENV "https://github.com/nik9play/vk-music-bot/blob/next/src/modules/env.ts"
    click HELP "https://github.com/nik9play/vk-music-bot/tree/next/src/helpers"
    click UTIL "https://github.com/nik9play/vk-music-bot/blob/next/src/utils.ts"
    click LOG "https://github.com/nik9play/vk-music-bot/blob/next/src/logger.ts"
    click PF "https://github.com/nik9play/vk-music-bot/tree/next/Procfile"
    click AJ "https://github.com/nik9play/vk-music-bot/blob/next/app.json"
    click TSC "https://github.com/nik9play/vk-music-bot/blob/next/tsconfig.json"
    click ESL "https://github.com/nik9play/vk-music-bot/blob/next/.eslintrc.json"
    click PRE "https://github.com/nik9play/vk-music-bot/blob/next/.prettierrc.json"

    %% Styles
    classDef core fill:#D0E7FF,stroke:#3399FF
    classDef orchestration fill:#DFF2D8,stroke:#3B8B0B
    classDef external fill:#FFE0B2,stroke:#FF8C00
    classDef utils fill:#F2F2F2,stroke:#999999

    class C,EV,BIM,COMI,BUTI,MODI,SELI,CMDM,BUTM,MODM,SHM,PM,BP,VKL,VKT,YML,BL core
    class SM,APIS,IPCM,ALN,CLR,CID,CLINFO,DEST,GETN,RLN,SP orchestration
    class DAPI,LAVAL,VKAPI,YMAPI external
    class DB,ENV,HELP,UTIL,LOG,PF,AJ,TSC,ESL,PRE utils
```
