# rainyxeon/byteblaze architecture

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

- Interactive diagram: https://gitdiagram.com/rainyxeon/byteblaze
- Repository: https://github.com/rainyxeon/byteblaze

## Overview

##### Project Type and Purpose
- ByteBlaze is a full-stack TypeScript/Node.js Discord music bot.
- It uses a cluster model (master + multiple workers) to scale across shards.
- It connects to external Lavalink/Nodelink nodes for audio streaming, persists settings in pluggable databases (MySQL, MongoDB, Postgres, JSON), and exposes a small HTTP/WS web service for remote control/status.

##### Top-Level Components
- Discord Gateway API
- Lavalink/Nodelink Audio Nodes
- Supported Music Sources (YouTube, SoundCloud, Spotify, etc.)
- Database Service (MySQL/MongoDB/Postgres/JSON storage)
- Third-Party Services (Top.gg, optional webhooks)
b. Bot Cluster
- Cluster Manager (src/cluster/core.ts + manager.ts)
- Worker Processes (spawned via Node.js cluster, each handling shards)
c. Application Layers in Each Worker
1. Handlers
– Command Loader & Dispatcher (src/handlers/…)
– Event Loader & Dispatcher (client, guild, node, player, shard, track, websocket)
2. Business Logic & Services (src/services/…)
– Lavalink Auto-Reconnect, Auto-Fix services
– Permission, Rate-limit, Blacklist, Premium, Playlist, Config, Logger, YAML Parser, Top.gg integration
3. Database Access
– Driver abstraction layer (src/database/driver/*.ts)
– Schema definitions & setup scripts (src/database/schema & setup)
– Handler & KeyChecker (src/database/handler.ts)
4. Command & Button Modules
– Slash commands (src/commands/…)
– Button interactions (src/buttons/…)
5. Utilities & Structures
– Common utilities (time conversion, formatting)
– Extended classes (Queue, Player, Localization)
d. Web Service (src/web/)
– HTTP REST endpoints (getStatus, getQueueStatus, postCreatePlayer, patchControl, etc.)
– WebSocket server for push updates to clients

##### Component Relationships and Data Flows
- Discord Gateway → Cluster Manager → Worker
- Workers receive shard events, route through event handlers → services → send API calls back to Discord.
- Worker ↔ Lavalink Node
- Audio control commands (play, pause, seek) via WebSocket to Lavalink.
- Lavalink → player events → worker event handlers.
- Worker ↔ Database
- Services persist/fetch guild- and user-level settings, premium status, playlists, prefixes.
- Worker ↔ Web Service
- Exposes REST/WS for external dashboards or remote control (shows playback state, queue, allows control).
- Worker ↔ External Music Sources
- Audio metadata and streams pulled by Lavalink or downloaded via plugins.
- Worker ↔ Top.gg
- Bot analytics / vote tracking via HTTP API.

##### Architectural Patterns and Principles
- Cluster Pattern (Node.js built-in cluster for horizontal scalability)
- Modular Separation of Concerns: handlers, services, database, utilities, commands/buttons
- Adapter/Driver Pattern for pluggable database backends
- Observer/Publisher for event handling (Discord events, player events, shard events)
- Layered architecture in each worker: API Layer (Discord + Web), Business Logic Layer (services), Data Layer (database & Lavalink)

##### Essential Elements
- Clear component labels and responsibilities
- Cluster boundary with Master vs Worker roles
- Database abstraction layer and supported backends
- Web REST + WS interface module separate from the Discord bot flow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Services"
        direction TB
        Discord["Discord Gateway API"]:::external
        Lavalink["Lavalink/Nodelink Nodes"]:::external
        MusicSources["Music Sources (YouTube, Spotify, etc.)"]:::external
        DatabaseService["Database Service\n(MySQL/MongoDB/Postgres/JSON)"]:::external
        Topgg["Top.gg & Webhooks"]:::external
    end

    %% Cluster
    subgraph "Bot Cluster" 
        direction TB
        Master["Cluster Manager\n(core.ts, index.ts, manager.ts)"]:::core
        Worker["Worker Process\n(index.ts)"]:::core
    end

    %% Worker internals
    subgraph "Worker" 
        direction TB
        Handlers["Handlers Layer\n(loadEvents.ts, loadCommand.ts)"]:::core
        Services["Business Services\n(AutoReconnect, Blacklist, Topgg, YAMLParse...)"]:::core
        DBAccess["Database Access\n(driver, schema, handler)"]:::data
        Commands["Slash Commands\n(src/commands/)"]:::core
        Buttons["Button Interactions\n(src/buttons/)"]:::core
        Utilities["Utilities & Structures\n(ConvertTime, ExtendedPlayer...)"]:::core
    end

    %% Web Service
    subgraph "Web/API Layer" 
        direction TB
        WebServer["HTTP/WS Server\n(server.ts, websocket.ts)"]:::api
        Routes["REST Endpoints\n(getStatus, postCreatePlayer, patchControl...)"]:::api
    end

    %% Data Stores
    Schema["DB Schemas & Setup"]:::data
    Drivers["DB Drivers\n(json.ts, mongodb.ts, mysql.ts, postgres.ts)"]:::data

    %% Deployment
    Docker["Deployment Artifacts\nDockerfile, docker-compose.yml"]:::core

    %% Connections
    Discord -->|"Gateway Events"| Master
    Master -->|"Shard Assignment"| Worker
    Worker -->|"Events"| Handlers
    Handlers -->|"Calls"| Services
    Services -->|"Persist/Fetch"| DBAccess
    DBAccess -->|"Uses"| Drivers
    DBAccess -->|"Uses"| Schema
    Services -->|"Audio Control"| Lavalink
    Lavalink -->|"Player Events"| Handlers
    Worker -->|"Pull Metadata"| MusicSources
    Services -->|"Vote Tracking"| Topgg
    Worker -->|"Exposes"| WebServer
    WebServer -->|"Handles"| Routes
    Routes -->|"Controls"| Services
    Routes -->|"Queries"| DBAccess
    Docker --> Master
    Docker --> Lavalink
    Docker --> DatabaseService

    %% Click Events
    click Master "https://github.com/rainyxeon/byteblaze/blob/main/src/cluster/core.ts"
    click Master "https://github.com/rainyxeon/byteblaze/blob/main/src/cluster/index.ts"
    click Master "https://github.com/rainyxeon/byteblaze/blob/main/src/manager.ts"
    click Worker "https://github.com/rainyxeon/byteblaze/blob/main/src/index.ts"
    click Handlers "https://github.com/rainyxeon/byteblaze/blob/main/src/handlers/index.ts"
    click Handlers "https://github.com/rainyxeon/byteblaze/blob/main/src/handlers/loadEvents.ts"
    click Handlers "https://github.com/rainyxeon/byteblaze/blob/main/src/handlers/loadCommand.ts"
    click Services "https://github.com/rainyxeon/byteblaze/blob/main/src/services/AutoReconnectBuilderService.ts"
    click Services "https://github.com/rainyxeon/byteblaze/blob/main/src/services/BlacklistService.ts"
    click Services "https://github.com/rainyxeon/byteblaze/blob/main/src/services/CheckPermissionService.ts"
    click Drivers "https://github.com/rainyxeon/byteblaze/blob/main/src/database/driver/json.ts"
    click Drivers "https://github.com/rainyxeon/byteblaze/blob/main/src/database/driver/mongodb.ts"
    click Drivers "https://github.com/rainyxeon/byteblaze/blob/main/src/database/driver/mysql.ts"
    click Drivers "https://github.com/rainyxeon/byteblaze/blob/main/src/database/driver/postgres.ts"
    click Schema "https://github.com/rainyxeon/byteblaze/tree/main/src/database/schema/"
    click Handlers "https://github.com/rainyxeon/byteblaze/blob/main/src/handlers/Commands/loadCommands.ts"
    click Services "https://github.com/rainyxeon/byteblaze/blob/main/src/services/TopggService.ts"
    click Commands "https://github.com/rainyxeon/byteblaze/tree/main/src/commands/"
    click Buttons "https://github.com/rainyxeon/byteblaze/tree/main/src/buttons/"
    click Utilities "https://github.com/rainyxeon/byteblaze/blob/main/src/utilities/ConvertTime.ts"
    click WebServer "https://github.com/rainyxeon/byteblaze/blob/main/src/web/server.ts"
    click WebServer "https://github.com/rainyxeon/byteblaze/blob/main/src/web/websocket.ts"
    click Routes "https://github.com/rainyxeon/byteblaze/blob/main/src/web/route/getStatus.ts"
    click Routes "https://github.com/rainyxeon/byteblaze/blob/main/src/web/route/postCreatePlayer.ts"
    click Routes "https://github.com/rainyxeon/byteblaze/blob/main/src/web/route/patchControl.ts"
    click Docker "https://github.com/rainyxeon/byteblaze/tree/main/Dockerfile"
    click Docker "https://github.com/rainyxeon/byteblaze/blob/main/docker-compose.yml"

    %% Styles
    classDef external fill:#D0E6FF,stroke:#000
    classDef core fill:#D1F2A5,stroke:#000
    classDef data fill:#FAD7A0,stroke:#000
    classDef api fill:#E8DAEF,stroke:#000
```
