enteee/djalgorhythm repository overview

cp .env.example .env

# Build and run (recommended)
make build
./bin/djalgorhythm

# Run directly from source
go run ./cmd/djalgorhythm

# Custom config and debug logging
./bin/djalgorhythm --config myconfig.env --log-level debug

User: https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV
Bot: ✅ Added: Daft Punk - One More Time

User: "Something upbeat by Taylor Swift"
Bot: 🎵 Did you mean Taylor Swift - Anti-Hero (2022)?
     React 👍 to add or 👎 to skip

User: https://www.youtube.com/watch?v=dQw4w9WgXcQ
Bot: 🎵 Found: Rick Astley - Never Gonna Give You Up (1987)
     React 👍 to add or 👎 to skip

User: https://www.beatport.com/track/love-songs-feat-kosmo-kint/21977538
Bot: 🎵 Found: Prospa, Kosmo Kint - Love Songs (feat. Kosmo Kint) (Extended Mix)
     React 👍 to add or 👎 to skip

User: https://soundcloud.com/rick-astley-official/never-gonna-give-you-up-4
Bot: 🎵 Found: Rick Astley - Never Gonna Give You Up
     React 👍 to add or 👎 to skip

graph TD
    A["💬 User sends message"] --> B{"🤔 What type?"}
    B -->|"🔗 Spotify Link"| C1["🔍 Check for duplicates"]
    B -->|"🎥 Cross-Platform Link"| C3["🔍 Resolve & match to Spotify"]
    B -->|"💭 Free text"| E["🤖 4-stage LLM disambiguation"]

    C3 -->|"Success"| CONFIRM["👍 User confirms track?"]
    C3 -->|"Failed"| D["💬 Ask: Which song?"]

    C1 -->|"New track"| C2{"🛡️ Admin approval required?"}
    C1 -->|"Duplicate"| REJECT_DUP["❌ Duplicate track"]

    E --> CONFIRM

    CONFIRM -->|"Yes"| C1
    CONFIRM -->|"No"| D

    C2 -->|"Yes"| ADMIN["⏳ Await admin/community approval"]
    C2 -->|"No"| PRIORITY{"👑 Admin priority request?"}

    ADMIN -->|"Approved"| PRIORITY
    ADMIN -->|"Denied"| REJECT_DENY["❌ Track rejected"]

    PRIORITY -->|"Yes"| QUEUE["⚡ Add to queue (play next)"]
    PRIORITY -->|"No"| PLAYLIST["➕ Add to playlist"]

    QUEUE --> J["✅ Priority track queued!"]
    PLAYLIST --> J["✅ Added to playlist!"]

    style PLAYLIST fill:#1DB954
    style QUEUE fill:#FF6B35
    style J fill:#1DB954
    style A fill:#26A5E4
    style REJECT_DUP fill:#FF4444
    style REJECT_DENY fill:#FF4444
    style CONFIRM fill:#E67E22
    style C3 fill:#9B59B6

djalgorhythm --help

Flags:
      --admin-needs-approval                         Require approval even for admins (for testing)
      --community-approval int                       Number of 👍 reactions needed to bypass admin approval (0 disables feature)
      --config string                                config file (default is .env)
      --confirm-admin-timeout-secs int               Admin confirmation timeout in seconds (default 3600)
      --confirm-timeout-secs int                     Confirmation timeout in seconds (default 120)
      --flood-limit-per-minute int                   Maximum messages per user per minute (default 6)
      --generate-env-example                         Generate .env.example file from current configuration and exit
  -h, --help                                         help for djalgorhythm
      --language string                              Bot language (en, ch_be) (default "en")
      --llm-api-key string                           LLM API key
      --llm-model string                             LLM model name
      --llm-provider string                          LLM provider (openai, anthropic, ollama) - REQUIRED
      --log-format string                            log format (json, text) (default "text")
      --log-level string                             log level (debug, info, warn, error) (default "info")
      --max-queue-track-replacements int             Maximum queue track replacement attempts before auto-accepting (default 3)
      --queue-ahead-duration-secs int                Target queue duration in seconds (default 90)
      --queue-check-interval-secs int                Queue check interval in seconds (default 45)
      --queue-track-approval-timeout-secs int        Queue track approval timeout in seconds (default 30)
      --server-host string                           HTTP server host (default "127.0.0.1")
      --server-port int                              HTTP server port (default 8080)
      --shadow-queue-maintenance-interval-mins int   Shadow queue maintenance interval in minutes (default 5)
      --shadow-queue-max-age-hours int               Maximum age of shadow queue items in hours (default 2)
      --spotify-client-id string                     Spotify client ID
      --spotify-client-secret string                 Spotify client secret
      --spotify-oauth-bind-host string               Host for OAuth callback server to bind to (defaults to server-host, use 0.0.0.0 in containers)
      --spotify-playlist-id string                   Spotify playlist ID
      --telegram-bot-token string                    Telegram bot token
      --telegram-group-id int                        Telegram group ID

cmd/djalgorhythm/           # Main application entry point
internal/
  ├── chat/           # Unified chat frontend interface
  │   └── telegram/   # Telegram Bot API client
  ├── core/           # Domain types and message dispatcher
  ├── spotify/        # Spotify Web API client (zmb3/spotify)
  ├── llm/            # LLM providers (OpenAI, Anthropic stub, Ollama stub)
  ├── store/          # Dedup store (Bloom filter + LRU cache)
  ├── http/           # HTTP server, metrics, and web UI
  ├── flood/          # Flood protection and rate limiting
  └── i18n/           # Internationalization (en, ch_be)
pkg/
  ├── text/           # Message parsing and URL detection
  ├── fuzzy/          # String similarity and normalization
  └── musiclink/      # Cross-platform music link resolvers

# Enter development shell
devenv shell

# Available tools
devenv-help

# VS Code with extensions
code .

# Build binary
make build

# Run tests
make test

# Run all quality checks (fmt, vet, lint, test, build)
make check

# Clean build artifacts
make clean

# Build Docker images (multi-platform: linux/amd64, linux/arm64)
make snapshot-release

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detection
go test -race ./...

# Test specific package
go test ./internal/chat/telegram/

# Run with environment file
docker run --env-file .env -p 8080:8080 enteee/djalgorhythm:latest

# Check bot token is valid
curl "https://api.telegram.org/bot<TOKEN>/getMe"

# Verify bot is admin in group
# Check group ID is correct (negative number)

# Verify redirect URI matches Spotify app settings
# Check client ID and secret are correct
# Ensure playlist ID is valid and accessible

# Check API key is valid
# Verify model name is correct
# Monitor rate limits in logs

# Enable debug logging
DJALGORHYTHM_LOG_LEVEL=debug ./bin/djalgorhythm

# Or with flag
./bin/djalgorhythm --log-level debug