# ashokshau/tgmusicbot architecture

> Architecture diagram of the GitHub repository ashokshau/tgmusicbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashokshau/tgmusicbot
- Repository: https://github.com/ashokshau/tgmusicbot

## Overview

##### Project Type and Purpose
- This is a backend service (a Telegram Voice Chat music bot) built in Python.
- It connects to Telegram (bot API and voice chat API), streams music from third-party platforms (YouTube, Spotify, JioSaavn, etc.), applies caching and filtering, and persists state in MongoDB.
- It lives in a Docker container or can run directly on a VM/Heroku/tmux.

##### File Structure Insights
- Top-level files: Dockerfile, Procfile, setup scripts, CI workflows, sample.env for configuration.
- TgMusic package:
- __main__.py: entrypoint that launches the bot.
- logger.py: logging configuration.
- core/ directory: business-logic services (API wrappers, HTTPX client, downloader, cacher, config loader, database access, cookie manager, tgcalls integration, audio filters, thumbnail generator, utility helpers).
- modules/ directory: Telegram command handlers organized per feature (play, skip, queue, loop, volume, broadcast, admin, etc.). A utils subfolder holds shared helpers.
- cookies/ directory: management of cookie-based authentication for services.
- pyproject.toml & uv.lock: dependency definitions.

##### Key Components
- Telegram Layer
- Telegram Bot API (PyTDbot or Pyrogram) for incoming commands.
- Telegram Voice Chat API (PyTgCalls) for streaming audio.
- Command Handling Layer
- modules/ handlers parse updates and emit events or call core services.
- Core Services Layer
- Downloader service: fetches audio from YouTube, Spotify, JioSaavn via HTTPX or cookies.
- Cacher: stores downloaded content or metadata (in MongoDB or file cache).
- Filter/Processor: normalizes audio (volume adjust, format conversion via ffmpeg).
- Database: MongoDB for queue state, user settings, logs.
- Config Manager: reads environment variables (.env → _config).
- API Wrappers: modular wrappers under core/_jiosaavn, _spotify_dl_helper, _youtube, _httpx.
- Cookie Manager: fetches and saves cookies for sites.
- Telegram Integration: PyTgCalls for voice streaming, button generators, thumbnail maker.
- External Systems
- Third-party streaming platforms: YouTube, Spotify, JioSaavn etc.
- MongoDB Atlas or self-hosted MongoDB.
- Optional external API gateway (FallenApiBot) for anti-ban.
- Deployment & Infrastructure
- Docker container built via Dockerfile.
- Continuous Integration (GitHub Workflows).
- Heroku (Procfile/app.json) or standalone VM with tmux.
- Logging to Telegram group or console.

##### Relationships and Interactions
- Incoming Telegram Updates → Command Handler modules → invoke Core Services.
- Core Services → Downloader/API Wrappers → Third-party Platforms.
- Downloaded audio → Filter/Processor → PyTgCalls → streamed to Telegram Voice Chat.
- State changes (queue updates, user requests) → persisted in MongoDB via core/_database.
- Cacher checks cache first; on cache miss, triggers download.
- Config Manager supplies API keys, tokens, connection strings.
- Logger broadcasts runtime logs to a Telegram logger group or stdout.
- Docker container exposes no ports (communicates outbound to Telegram).

##### Architectural Patterns and Principles
- Modular Monolith: logical separation into “command modules” and “core services” within one process.
- Layered Architecture: Presentation (Telegram API), Application (modules), Domain (core), Infrastructure (MongoDB, Docker).
- Plugin-like modules: new commands added by dropping files in modules/.
- Event-driven command loop: Telegram update → dispatch to module → event triggers service calls.
- Single responsibility per core file (downloader, cacher, API wrapper).

##### Essential Details
- Environment configuration feeding into the Config Manager.
- CI/CD pipeline triggering Docker builds and deployments.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Telegram Layer
    Entrypoint["Main Entrypoint"]:::internal
    TelegramUpdates["Telegram Bot API Client"]:::external
    VoiceChatAPI["Telegram Voice Chat API Client"]:::external

    %% Command Handler Layer
    subgraph "Command Handler Layer"
        Modules["Command Modules"]:::internal
        PlayHelpers["play_helpers.py"]:::internal
    end

    %% Core Services Layer
    subgraph "Core Services Layer"
        Downloader["Downloader Service"]:::internal
        HTTPX["HTTPX Client"]:::internal
        YouTube["YouTube API Wrapper"]:::internal
        Spotify["Spotify Helper"]:::internal
        JioSaavn["JioSaavn API Wrapper"]:::internal
        Cacher["Caching Service"]:::internal
        Filters["Audio Filters & Processing"]:::internal
        Database["MongoDB Access"]:::external
        Config["Configuration Manager"]:::internal
        CookieManager["Cookie Manager"]:::internal
        CookiesDir["Cookies Directory"]:::internal
        Thumbnails["Thumbnail Generator"]:::internal
        Buttons["Button/Keyboard Generator"]:::internal
        Logger["Logger"]:::internal
        Utils["Core Utility Helpers"]:::internal
        VoiceStream["Voice Stream (PyTgCalls)"]:::external
    end

    %% Third-Party Platforms
    subgraph "Third-Party Platforms"
        YouTubeExt["YouTube"]:::external
        SpotifyExt["Spotify"]:::external
        JioSaavnExt["JioSaavn"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Docker["Docker"]:::infra
        CI["CI/CD Workflows"]:::infra
        Heroku["Heroku / VM"]:::infra
        Env["Environment Config (.env)"]:::infra
        Metadata["Project Metadata"]:::infra
    end

    %% Relationships
    Entrypoint -->|launches| TelegramUpdates
    Entrypoint -->|launches| VoiceChatAPI

    TelegramUpdates -->|updates| Modules
    Modules -->|uses helpers| PlayHelpers
    Modules -->|invoke| Downloader
    Modules -->|invoke| Cacher

    Cacher -->|cache miss| Downloader
    Downloader -->|fetch via| HTTPX
    HTTPX -->|API calls| YouTubeExt
    HTTPX -->|API calls| SpotifyExt
    HTTPX -->|API calls| JioSaavnExt

    Downloader -->|raw audio| Filters
    Filters -->|processed audio| VoiceStream
    VoiceStream -->|stream to| VoiceChatAPI

    Modules -->|generate| Buttons
    Modules -->|generate| Thumbnails

    Modules -->|log events| Logger
    Downloader -->|log events| Logger
    Filters -->|log events| Logger

    Modules -->|read/write| Database
    Modules -->|read config| Config
    Downloader -->|read config| Config
    HTTPX -->|read config| Config
    Database -->|store state| Database

    CookieManager -->|provide cookies| HTTPX
    CookieManager -->|provide cookies| Downloader
    CookiesDir -->|persist| CookieManager

    Config -->|env vars| Env
    CI -->|build image| Docker
    CI -->|deploy| Heroku
    Docker -->|runs service| Entrypoint

    %% Click Events
    click Entrypoint "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/__main__.py"
    click TelegramUpdates "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_telegram.py"
    click VoiceStream "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_tgcalls.py"
    click Modules "https://github.com/ashokshau/tgmusicbot/tree/master/TgMusic/modules/"
    click PlayHelpers "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/modules/utils/play_helpers.py"
    click Downloader "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_downloader.py"
    click HTTPX "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_httpx.py"
    click YouTube "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_youtube.py"
    click Spotify "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_spotify_dl_helper.py"
    click JioSaavn "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_jiosaavn.py"
    click Cacher "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_cacher.py"
    click Filters "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_filters.py"
    click Database "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_database.py"
    click Config "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_config.py"
    click CookieManager "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/_save_cookies.py"
    click CookiesDir "https://github.com/ashokshau/tgmusicbot/tree/master/TgMusic/cookies/"
    click Thumbnails "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/thumbnails.py"
    click Buttons "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/buttons.py"
    click Logger "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/logger.py"
    click Utils "https://github.com/ashokshau/tgmusicbot/blob/master/TgMusic/core/utils.py"
    click Docker "https://github.com/ashokshau/tgmusicbot/tree/master/Dockerfile"
    click CI "https://github.com/ashokshau/tgmusicbot/blob/master/.github/workflows/code-fixer.yml"
    click CI "https://github.com/ashokshau/tgmusicbot/blob/master/.github/workflows/dependency-update.yml"
    click Heroku "https://github.com/ashokshau/tgmusicbot/tree/master/Procfile"
    click Env "https://github.com/ashokshau/tgmusicbot/blob/master/sample.env"
    click Metadata "https://github.com/ashokshau/tgmusicbot/blob/master/pyproject.toml"
    click Metadata "https://github.com/ashokshau/tgmusicbot/blob/master/uv.lock"

    %% Styles
    classDef internal fill:#a2d5ab,stroke:#2f7a3e,color:#0c3;
    classDef external fill:#a7c7e7,stroke:#2e5c8a,color:#024;
    classDef infra fill:#f5cda1,stroke:#b37e24,color:#b44;
```
