How hmes98318/music-disc works
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)