initial

ARCHITECTURE.md

@@ -0,0 +1,133 @@
+# 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