# hmes98318/music-disc architecture

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

- Interactive diagram: https://gitdiagram.com/hmes98318/music-disc
- Repository: https://github.com/hmes98318/music-disc

## Overview

##### Project type and purpose
- Music-Disc is a full-stack Node.js/TypeScript application combining:
- A Discord bot (discord.js v14 + LavaShark) that handles music commands and connects to Lavalink nodes for audio streaming.
- A web dashboard (Express + static HTML/CSS/JS) to monitor and control the bot and its Lavalink nodes.
- Optional local Lavalink node deployment via Docker/Docker-Compose.

##### File structure
- Top-level “src” directory contains all backend code:
- Controllers (Controller.ts, ShardingController.ts)
- Command modules under src/commands
- Event handlers under src/events (discord and lavashark subfolders)
- Loader modules under src/loader to register commands, events, i18n, local node, site, etc.
- Utility libraries under src/lib (Logger, API server, session manager, localnode controller)
- Types under src/@types
- “public” holds static assets (images, emojis) served by the dashboard server.
- “views” holds HTML templates, CSS, and client-side JS for the dashboard UI.
- “server” directory includes application.yml & docker-compose.yml for spinning up a local Lavalink service.
- Config files: .env.example, config.js, docker-compose.yml, Dockerfile; CI/CD workflows under .github.

##### Extract additional insights from README
- Bot communicates with Discord API and uses LavaShark to route audio requests to Lavalink nodes (remote or local).
- Web dashboard exposes HTTP endpoints on SITE_PORT, with session management (USER or OAuth2).
- Deployment can be via Node.js or Docker; also supports spinning up a standalone Lavalink container.

##### Main components and interactions
a. Components
- Discord API (external)
- Music-Disc Bot Service
– Discord.js client
– LavaShark client (manages pool of Lavalink nodes)
– Command & event subsystems
– Session Manager (IP blocker, sessions)
– Express HTTP server (dashboard API)
- Lavalink Nodes
– External hosted Lavalink clusters
– Optional local Lavalink node process (server/application.yml + Docker)
- Web Dashboard Frontend
– Static HTML/CSS/JS served by the Bot’s Express server
– REST/WebSocket calls to dashboard endpoints
- Persistence (optional)
– nodelist.json, blacklist.json for node config (mounted volumes in Docker)
b. Interactions
1. Bot Service ←→ Discord API: receives slash commands and voice state updates
2. Bot Service → LavaShark Client → one of the Lavalink Nodes: send play/skip/seek requests
3. Lavalink Node → Bot Service: returns track events (trackStart, trackEnd, errors)
4. Bot Service (Express) ←→ Dashboard Frontend:
– Serves static assets
– Provides HTTP endpoints for viewing server status, nodes list, logs, metrics
5. Session Manager sits between Dashboard requests and bot endpoints to enforce authentication.
c. Architectural patterns
- Modular Event-Driven design (Discord events and LavaShark events)
- Command pattern for bot commands
- MVC-like separation:
– Model: Lavalink nodes & session state
– Controller: command handlers & HTTP controllers
– View: HTML templates + client-side JS
- Loader/Initializer pattern for bootstrapping modules
d. Key technologies
- Node.js (v18+), TypeScript
- discord.js v14, LavaShark, Lavalink (v4)
- Express.js for dashboard API
- Docker & Docker Compose for containerization
- i18next for localization (src/lib/i18n)
- SessionManager & IPBlocker for dashboard auth

##### Diagramming recommendations
- Green for external services (Discord API, external Lavalink)
- Blue for Bot Service components (Discord client, command/event modules, Express server)
- Orange for Lavalink nodes (local vs. remote)
- Gray for static assets (public/views)
- Data flow (Discord → Bot → Lavalink → Bot → Discord voice channel)
- Control flow (Dashboard UI → Express endpoints → Session Manager → Bot internals)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    DiscordAPI["Discord API"]:::external
    ExtLavalink["External Lavalink Nodes"]:::external

    %% Bot Service Container
    subgraph "Music-Disc Bot Service"
        direction TB
        Entry["Bot Entry Point\n(src/index.ts)"]:::bot
        App["Discord Client Init\n(src/App.ts)"]:::bot
        subgraph "Loaders & Init"
            direction TB
            Loader["Loader Modules\n(src/loader/)"]:::bot
            LavaLoad["LavaShark Client Loader\n(src/loader/loadLavaSharkEvents.ts)"]:::bot
            SiteLoad["Dashboard Site Loader\n(src/loader/loadSite.ts)"]:::bot
        end
        subgraph "Core Modules"
            direction TB
            Commands["Command Modules\n(src/commands/)"]:::bot
            DiscordEvents["Discord Event Handlers\n(src/events/discord/)"]:::bot
            LavaEvents["LavaShark Event Handlers\n(src/events/lavashark/)"]:::bot
            Controllers["Controllers\n(src/Controller.ts\nsrc/ShardingController.ts)"]:::bot
        end
        subgraph "Services & Utils"
            direction TB
            ExpressAPI["Express HTTP Server\n(src/lib/api/express.ts)"]:::bot
            SessionMgr["Session Manager\n(SessionManager & IPBlocker)"]:::bot
            Localization["Localization (i18n)\n(src/lib/i18n/)"]:::bot
            Logger["Logger & Utils"]:::bot
            LocalNodeCtrl["Local Lavalink Controller"]:::bot
        end
    end

    %% Local Lavalink Node
    subgraph "Local Lavalink Node" 
        direction TB
        AppYML["application.yml"]:::node
        ComposeYML["docker-compose.yml"]:::node
    end

    %% Dashboard Frontend
    subgraph "Web Dashboard Frontend"
        direction TB
        StaticAssets["Static Assets\n(public/)"]:::static
        Views["Views & Client JS\n(views/)"]:::static
    end

    %% Persistence
    Persist["nodelist.json / blacklist.json"]:::static

    %% Interactions
    DiscordAPI -->|slash commands & voice updates| App
    App -->|"register commands/events"| Loader
    Loader --> Commands
    Loader --> DiscordEvents
    Loader --> LavaEvents
    Loader --> LavaLoad
    LavaLoad -->|"init LavaShark"| LocalNodeCtrl
    LavaLoad -->|"init LavaShark"| ExtLavalink
    App --> Controllers
    Controllers --> ExpressAPI
    ExpressAPI --> SessionMgr
    SessionMgr --> Controllers
    ExpressAPI --> StaticAssets
    ExpressAPI --> Views
    StaticAssets -->|served| Views
    ExpressAPI --> Persist
    App --> Localization
    App --> Logger
    LocalNodeCtrl --> AppYML
    LocalNodeCtrl --> ComposeYML
    LocalNodeCtrl -->|"spawn local node"| AppYML
    LocalNodeCtrl -->|"spawn local node"| ComposeYML
    LavaEvents --> App
    Commands --> App
    DiscordEvents --> App
    App -->|"connect audio"| ExtLavalink
    ExtLavalink -->|"return track events"| App

    %% Click Events
    click Entry "https://github.com/hmes98318/music-disc/blob/main/src/index.ts"
    click App "https://github.com/hmes98318/music-disc/blob/main/src/App.ts"
    click Controllers "https://github.com/hmes98318/music-disc/blob/main/src/Controller.ts"
    click Controllers "https://github.com/hmes98318/music-disc/blob/main/src/ShardingController.ts"
    click Commands "https://github.com/hmes98318/music-disc/tree/main/src/commands/"
    click DiscordEvents "https://github.com/hmes98318/music-disc/tree/main/src/events/discord/"
    click LavaEvents "https://github.com/hmes98318/music-disc/tree/main/src/events/lavashark/"
    click Loader "https://github.com/hmes98318/music-disc/tree/main/src/loader/"
    click LavaLoad "https://github.com/hmes98318/music-disc/blob/main/src/loader/loadLavaSharkEvents.ts"
    click ExpressAPI "https://github.com/hmes98318/music-disc/blob/main/src/lib/api/express.ts"
    click SiteLoad "https://github.com/hmes98318/music-disc/blob/main/src/loader/loadSite.ts"
    click SessionMgr "https://github.com/hmes98318/music-disc/blob/main/src/lib/session-manager/SessionManager.ts"
    click SessionMgr "https://github.com/hmes98318/music-disc/blob/main/src/lib/session-manager/IPBlocker.ts"
    click LocalNodeCtrl "https://github.com/hmes98318/music-disc/blob/main/src/lib/localnode/LocalNodeController.ts"
    click AppYML "https://github.com/hmes98318/music-disc/blob/main/server/application.yml"
    click ComposeYML "https://github.com/hmes98318/music-disc/blob/main/server/docker-compose.yml"
    click StaticAssets "https://github.com/hmes98318/music-disc/tree/main/public/"
    click Views "https://github.com/hmes98318/music-disc/tree/main/views/"

    %% Styles
    classDef external fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef bot fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef node fill:#FFA500,stroke:#333,stroke-width:1px
    classDef static fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef main fill:#FFFFFF,stroke:#000,stroke-width:1px
```
