# tomato6966/lavalink-client architecture

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

- Interactive diagram: https://gitdiagram.com/tomato6966/lavalink-client
- Repository: https://github.com/tomato6966/lavalink-client

## Overview

##### Project type and purpose
- This is an open-source TypeScript library (“lavalink-client”) that integrates Discord bots (via discord.js) with Lavalink v4 audio servers.
- It provides a high-level Manager API, Player abstraction, queue management (with pluggable stores like in-memory or Redis), filter/equalizer support, event hooks, and helper utilities.
- The repo also contains:
- A documentation site under `/docs` (built with Astro + MDX).
- A “testBot” example showing how to integrate and exercise all features.

##### Top-level directory analysis
- `/src`: core library code, organized into:
- Manager layer: `LavalinkManager.ts`, `NodeManager.ts`, etc.
- Player layer: `Player.ts`, `Queue.ts`, `Filters.ts`.
- Types + utilities.
- `/testBot`: example Discord bot, with its own commands, event handlers, custom queue store/watcher, and env/config.
- `/docs`: static site source showing guides, version logs, API reference.
- CI/workflow files (`.github/workflows/*`), lint/config, project root `package.json` and `tsconfig.json`.

##### Key insights from README
- Manager ⇄ NodeManager ⇄ Lavalink server (WebSocket + REST).
- Discord.js client ⇄ Manager (raw voice events) ⇄ Discord Gateway/Sharding.
- Queue store is pluggable: default in-memory or custom (e.g. Redis).
- Extensive event emissions for player, track, queue, node lifecycle, debugging, lyrics, filters, sponsorblock plugin, etc.
- Emphasis on “automated handlings” (skip on errors, auto-reconnect, auto-destroy, resuming).

##### Main components
- Client Application (Discord.js Bot)
- Gateway Shard(s)
- Raw Voice/Message events → lavalink-client
- Lavalink-Client Library
- LavalinkManager (public API)
- NodeManager (manages WS connections to one or more Lavalink nodes)
- Player Instances + FilterManager + Queue (and QueueStore abstraction)
- CustomSearches module
- EventBus (emits player/node/queue events)
- External Systems
- Lavalink v4 Node(s) (WebSocket + REST endpoints)
- Optional Redis (custom QueueStore)
- Discord Gateway & Voice WebSocket
- Documentation site (Astro) — separate build pipeline

##### Relationships & data flows
- Bot sends raw Discord voice payloads → LavalinkManager.sendRawData() → NodeManager → Lavalink WS
- Bot calls `createPlayer()`, `player.play()`, `player.queue.add()`, etc. → LavalinkManager → NodeManager REST → Lavalink server
- Lavalink WS sends stats, track updates, events → NodeManager → LavalinkManager → Player + EventBus → Bot callback handlers
- QueueStore (memory or Redis): Player.queue.utils.sync() ↔ Redis for persistence or cross-shard sync
- CustomSearches (BandCamp, LavaSrc, LavaSearch) hit Lavalink REST search or external APIs, return Track objects

##### Architectural patterns & design principles
- Event-Driven: every state change emits strongly typed events to user code
- Layered Abstraction:
- Public API (LavalinkManager)
- Node management (WebSocket/REST orchestration)
- Player abstraction (connect/disconnect, play, pause, filters)
- Queue abstraction (pluggable stores, change watchers)
- Plugin-style extensibility: custom queue stores, queue watchers, custom search modules
- Separation of concerns: core library vs. example bot vs. documentation

- Public API (LavalinkManager)
- NodeManager (WS + REST handlers)
- Player instances (FilterManager, Queue)
- Utilities (CustomSearches, Utils)
- Discord Gateway → Bot (events) → LavalinkManager.sendRawData() → NodeManager → Lavalink WS
- Bot API calls (`play()`, `queue.add()`) → LavalinkManager → NodeManager REST → Lavalink REST
- NodeManager events → LavalinkManager → Bot callbacks
- Queue.sync → Redis (optional path)
- Player.search → CustomSearch modules → Lavalink REST or external API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Bot Layer
    subgraph "Client Bot (Example)" 
        direction TB
        Bot["Discord.js Client\n(Sharding, Intents)"]:::custom
        Commands["Example Commands"]:::custom
        Events["Example Event Handlers"]:::custom
        CustomQueue["Custom Queue Store & Watcher"]:::custom
        Resuming["Queue Sync Helpers"]:::custom
    end

    %% Library Core
    subgraph "lavalink-client Library"
        direction TB
        API["LavalinkManager (Public API)"]:::core
        NodeMgr["NodeManager\n(WS & REST Orchestration)"]:::core
        Node["Node\n(Single Lavalink Node)"]:::core
        Player["Player"]:::core
        Queue["Queue"]:::core
        Filters["Filters & Equalizer"]:::core
        Searches["CustomSearches"]:::core
        Utils["Utils & EventBus"]:::core
        Constants["Constants"]:::core
        Types["Typed Definitions"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        DiscordGW["Discord Gateway & Voice WS"]:::external
        Lavalink["Lavalink v4 Node\n(WebSocket + REST)"]:::external
        Redis["Redis (Optional QueueStore)"]:::external
        DocsSite["Documentation Site"]:::external
    end

    %% Connections: Bot -> Library -> External
    DiscordGW -->|"Voice & Message Events"| Bot
    Bot -->|"sendRawData() API Calls"| API
    API -->|"orchestrates"| NodeMgr
    NodeMgr -->|"WebSocket"| Lavalink
    NodeMgr -->|"REST/HTTP"| Lavalink
    Lavalink -->|"WS Events/Stats"| NodeMgr
    NodeMgr -->|"emits events"| API
    API -->|"callbacks to"| Bot

    Bot -->|"play(), queue.add()"| API
    API -->|"REST Calls"| NodeMgr

    Player -->|"uses"| Queue
    Player -->|"applies"| Filters
    Player -->|"emits via"| Utils

    Queue -->|"sync()↔"| Redis
    Searches -->|"track search"| Lavalink
    Searches -->|"external API"| External

    %% Click Events
    click DocsSite "https://github.com/tomato6966/lavalink-client/tree/main//docs"
    click Bot "https://github.com/tomato6966/lavalink-client/tree/main/testBot"
    click Commands "https://github.com/tomato6966/lavalink-client/tree/main/testBot/commands/"
    click Events "https://github.com/tomato6966/lavalink-client/tree/main/testBot/events/"
    click CustomQueue "https://github.com/tomato6966/lavalink-client/tree/main/testBot/Utils/CustomClasses/"
    click Resuming "https://github.com/tomato6966/lavalink-client/blob/main/testBot/Utils/handleResuming.ts"
    click API "https://github.com/tomato6966/lavalink-client/blob/main/src/index.ts"
    click API "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/LavalinkManager.ts"
    click NodeMgr "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/NodeManager.ts"
    click Node "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/Node.ts"
    click Player "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/Player.ts"
    click Queue "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/Queue.ts"
    click Filters "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/Filters.ts"
    click Searches "https://github.com/tomato6966/lavalink-client/tree/main/src/structures/CustomSearches/"
    click Utils "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/Utils.ts"
    click Constants "https://github.com/tomato6966/lavalink-client/blob/main/src/structures/Constants.ts"
    click Types "https://github.com/tomato6966/lavalink-client/tree/main/src/structures/Types/"
    click DocsSite "https://github.com/tomato6966/lavalink-client/blob/main/docs/astro.config.mjs"
    click DocsSite "https://github.com/tomato6966/lavalink-client/blob/main/docs/package.json"
    click DocsSite "https://github.com/tomato6966/lavalink-client/blob/main/.github/workflows/deployDocs.yml"
    click DocsSite "https://github.com/tomato6966/lavalink-client/blob/main/.github/workflows/publishAnyCommit.yml"

    %% Styles
    classDef core fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef custom fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100
```
