Introduction & Ecosystem Overview
High-level overview of the services, integrations, and infrastructure powering the Musiva ecosystem.
Welcome to the Musiva Developer & Infrastructure Documentation. This documentation platform covers the technical architecture, microservices, third-party music integrations, and managed audio infrastructure that power the Musiva platform.
Musiva is structured around a separation of responsibilities. Instead of tightly coupling audio decoding, metadata retrieval, chart analytics, and player session management inside a monolithic application, Musiva utilizes specialized internal services and an abstraction gateway.
Architectural Pillars
Specialized Services
Dedicated services for Spotify chart aggregation, Deezer ARL token rotation, Spotify partner tokens, and YouTube streaming.
Lavalink Gateway
Intelligent connection broker that handles node clustering, health monitoring, zero-downtime failover, and IP address masking.
Managed Infrastructure
Public and internal Lavalink access tiers, automated Patreon membership provisioning, and centralized quota management.
Core Backend & WebPlayer
Business logic, Discord bot command interactions, WebPlayer dashboard, and embedded Web Activities.
Why Separate Services?
Operating a high-scale music streaming platform requires resilience against rate limits, token expirations, and node downtime. Musiva solves these challenges through modular architecture:
- Independent Lifecycle Management: Token managers like the Deezer ARL service and Spotify Tokener maintain their own background renewal loops without restarting the core bot or web application.
- Infrastructure Resilience: If a Lavalink node fails or requires operating system maintenance, the Gateway automatically migrates active sessions to healthy nodes without disconnecting Discord voice listeners.
- Security by Abstraction: Third-party bot developers and public clients connect exclusively to
gateway.musiva.app, preventing exposure of origin node IP addresses and mitigating DDoS risks. - Optimized Audio Quality: Native lossless flac and high-bitrate MP3 decoding from Deezer is integrated directly with fallback logic to Apple Music, Tidal, Spotify, and YouTube.
Quick Navigation
Explore the major sections of this documentation:
- System Architecture — Full architectural flowchart and responsibility breakdown.
- Internal Services — Deep dive into TopChart, Deezer ARL, Spotify Tokener, and YouTube integration.
- Lavalink Infrastructure — Gateway architecture, dynamic load balancing, and failover behavior.
- Gateway as a Service — Tiers, player limits, and automated Patreon integration.
- Internal Systems — Main backend, WebPlayer, Web Activities, and deprecated subsystems.