# Discord Jukebox Bot - Architecture

This document describes the architecture and design principles of the Discord Jukebox Bot application.

## Overview

Discord Jukebox Bot is a Go application that connects to a Discord server and a Subsonic-compatible music server to provide a jukebox experience in Discord voice channels. The bot fetches random tracks from the configured Subsonic server and streams them to a Discord voice channel.

## Project Structure

The project follows a clean, modular structure:

```
discord-jukebox-bot/
├── cmd/                    # Command-line applications
│   └── bot/                # Main bot application
│       └── main.go         # Entry point
├── pkg/                    # Library packages
│   ├── config/             # Configuration management
│   ├── commands/           # Command registration and processing
│   ├── discord/            # Discord integration
│   └── subsonic/           # Subsonic API client
├── README.md               # Project documentation
└── ARCHITECTURE.md         # This architecture document
```

## Component Design

### Configuration (pkg/config)

The configuration package handles loading and validating environment variables. It uses the `JUKEBOX_` prefix for all environment variables to avoid conflicts with other applications.

Key responsibilities:
- Loading configuration from environment variables and .env files
- Providing default values for optional settings
- Validating required configuration
- Cleaning and normalizing input values (like Guild IDs)

### Subsonic Client (pkg/subsonic)

The Subsonic client package provides a client for interacting with Subsonic-compatible music servers.

Key responsibilities:
- Authenticating with the Subsonic server
- Fetching random songs with detailed metadata
- Generating streaming URLs for audio content
- Handling various API response formats (JSON/XML)

### Discord Bot (pkg/discord)

The Discord bot package manages the connection to Discord and provides voice channel functionality.

Key responsibilities:
- Connecting to Discord
- Managing voice channel connections
- Registering and handling slash commands
- Real-time audio encoding and streaming to voice channels
- Processing audio data from Subsonic to Discord-compatible Opus format

### Commands (pkg/commands)

The commands package sets up and registers all the bot commands, providing a clean interface for adding new commands.

Key responsibilities:
- Registering command handlers
- Providing a centralized setup function for all components

## Data Flow

1. The application starts in `cmd/bot/main.go`, which:
   - Loads configuration
   - Sets up the Discord bot and command handlers
   - Starts the bot and waits for termination signals

2. When a user invokes the `/jukebox play` command:
   - The bot joins the user's voice channel
   - Fetches random songs from the Subsonic server
   - Retrieves audio streams from Subsonic
   - Transcodes the audio to Opus format in real-time
   - Streams the encoded audio to the Discord voice channel

3. The jukebox player manages the playlist and playback:
   - Maintains a queue of songs
   - Fetches more songs when the queue is low
   - Handles play, stop, and skip commands
   - Manages audio encoding and streaming processes
   - Controls volume and timing of audio playback

## Extension Points

The application is designed for easy extension:

1. **Adding New Commands**: 
   - Define new command handlers in `pkg/commands/setup.go`
   - Register them with the `RegisterCustomCommand` function

2. **Supporting More Subsonic Features**:
   - Extend the Subsonic client in `pkg/subsonic/client.go`
   - Add new API methods as needed

3. **Adding New Jukebox Features**:
   - Extend the `JukeboxPlayer` in `pkg/discord/jukebox.go`
   - Add new command handlers for the features

## Concurrency Model

The application uses Go's concurrency primitives to handle multiple tasks:

- Mutexes protect shared state (playlist, playing status)
- Channels coordinate between the main goroutine and audio playback goroutines
- Dedicated goroutines handle audio encoding and streaming
- Precise timing controls for audio frame delivery
- The main goroutine handles signals for graceful shutdown

## Error Handling

Error handling follows Go's idiomatic approach:
- Functions return errors rather than using exceptions
- Errors are propagated up the call stack
- Critical errors are logged and cause application termination
- Non-critical errors (like playback issues) are logged and the application continues

## Future Improvements

Potential areas for future enhancement:

1. **Enhanced Audio Processing**: Add support for more audio formats and quality settings
2. **Extended Commands**: Add playlist management, search functionality, and more playback controls
3. **Persistent State**: Save state between restarts (current playlist, volume settings)
4. **Multiple Guild Support**: Support running in multiple Discord servers simultaneously
5. **Metrics and Monitoring**: Add telemetry for monitoring bot health and usage
6. **Voice Effects**: Add audio effects like equalizer, normalization, and bass boost
7. **Advanced Subsonic Features**: Support album art, playlists, and other Subsonic-specific features