# theteamalexa/alexamusic architecture

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

- Interactive diagram: https://gitdiagram.com/theteamalexa/alexamusic
- Repository: https://github.com/theteamalexa/alexamusic

## Overview

##### Project Type & Purpose
- AlexaMusic is a monolithic Python service—a Telegram Bot (and optional Userbot)—for in-chat audio/video playback. It leverages Pyrogram (bot & user sessions), Py-TgCalls for voice‐chat streaming, yt-dlp for media extraction, and MongoDB for state persistence.

##### High-Level File/Directory Analysis
- “AlexaMusic/”
- core/ – the engine (bot initialization, call management, cookie handling, Git/dir utilities, MongoDB wrappers, userbot auto-join)
- platforms/ – adapter modules for each music source (YouTube, Spotify, SoundCloud, Apple, etc.)
- plugins/ – command handlers organized by role (admins, bot, devs, misc, play, sudo, tools)
- utils/ – shared utilities (database models, decorators, formatters, inline query builders, stream queue, thumbnails, logging)
- Top-level helpers: app.py/.env/config, Dockerfile/docker-compose.yml, heroku/koyeb/render manifests, genstring.py (session generator), requirements.txt

##### README Insights
- Tech stack: Python 3, Pyrogram, Py-TgCalls, yt-dlp
- External dependencies: Telegram Bot API, MongoDB URI, browser cookies for YouTube
- Deployment targets: Docker, Heroku, Render, Koyeb, Scalingo
- Command-based plugin architecture drives all user interactions

##### Main Architectural Components
a. Telegram Layer
- Bot Client (Pyrogram)
- Optional Userbot Client (Pyrogram) – auto-join voice chats
b. Core Engine
- Update dispatcher → plugin loader → command router
- Call manager (joins/leaves voice chats)
- Cookie manager for signed-in YouTube access
- Git/dir utilities (self-update, logs, metrics)
c. Platform Adapters
- YouTube, Spotify, SoundCloud, Apple, Resso, Carbon – each implements a standard interface for “search,” “stream,” “download”
d. Media Extraction & Streaming
- yt-dlp (downloads or streams media)
- Py-TgCalls (streams audio/video into Telegram voice chats)
e. Persistence
- MongoDB (chats, user settings, gban, sudo, assistant database, themes, on/off flags, pm-permit)
f. Configuration & Secrets
- .env / config/config.py / sample.env / genstring.py (session generation)
g. Deployment / CI
- Docker / docker-compose
- Heroku, Render, Koyeb, Scalingo manifests
- GitHub Actions (black formatting)

##### Component Interactions & Data Flows
- User → Telegram Bot API → Bot Client
- Bot Client → Core command dispatcher → Loads appropriate Plugin
- Plugin → Core services (call manager, platform adapter, database)
- Platform Adapter → External music API (or yt-dlp) → Returns media stream/URL
- Call Manager + Py-TgCalls → Inject media stream into Telegram Voice Chat
- Database reads/writes on each stateful operation (queues, settings, bans)
- Logging and metrics captured at each layer

##### Architectural Patterns & Principles
- Modular Plugin Architecture (separation of commands by concern)
- Adapter Pattern (uniform interface to heterogeneous music sources)
- Layered Design (Telegram layer → business logic → data persistence)
- Dependency Injection via config and environment variables

##### Final Checklist
- Clear, concise labels on every component
- Layer separation (Deployment, Application, Service, Data)
- Callouts for critical environment variables (API keys, MongoDB URI, session strings)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Layer
    subgraph "Deployment Layer"
        Docker["Docker / docker-compose"]:::deploy
        Heroku["Heroku / Procfile"]:::deploy
        Render["Render / render.yaml"]:::deploy
        Koyeb["Koyeb / koyeb.yaml"]:::deploy
        CICD["GitHub Actions"]:::deploy
    end

    %% Application Layer
    subgraph "Application Layer"
        BotClient["Bot Client (Pyrogram)"]:::app
        UserbotClient["Userbot Client (Pyrogram)"]:::app
        CoreMain["Core Engine (__main__.py)"]:::app
    end

    %% Service Layer
    subgraph "Service Layer"
        subgraph "Core Modules"
            Dispatcher["Update Dispatcher"]:::core
            PluginLoader["Plugin Loader"]:::core
            CommandRouter["Command Router"]:::core
            CallManager["Call Manager"]:::core
            CookieManager["Cookie Manager"]:::core
            GitUtils["Git Utilities"]:::core
            DirUtils["Directory Utilities"]:::core
            MongoWrapper["MongoDB Wrapper"]:::core
        end
        subgraph "Plugins"
            AdminPlugins["Admins"]:::plugin
            BotPlugins["Bot"]:::plugin
            DevPlugins["Devs"]:::plugin
            MiscPlugins["Misc"]:::plugin
            ModulePlugins["Modules"]:::plugin
            PlayPlugins["Play"]:::plugin
            SudoPlugins["Sudo"]:::plugin
            ToolsPlugins["Tools"]:::plugin
        end
        subgraph "Adapters"
            YouTube["YouTube Adapter"]:::adapter
            Spotify["Spotify Adapter"]:::adapter
            SoundCloud["SoundCloud Adapter"]:::adapter
            Apple["Apple Music Adapter"]:::adapter
            Resso["Resso Adapter"]:::adapter
            Carbon["Carbon Adapter"]:::adapter
            TelegramAdapter["Telegram Adapter"]:::adapter
        end
        subgraph "Media Streaming"
            YTDLP["yt-dlp"]:::external
            PyTgCalls["Py-TgCalls"]:::external
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        MongoDB["MongoDB"]:::database
        CookiesStore["Cookie Storage"]:::cookie
    end

    %% External Services
    TelegramAPI["Telegram API"]:::external

    %% Connections
    TelegramAPI -->|"updates"| BotClient
    BotClient -->|"start"| CoreMain
    CoreMain --> Dispatcher
    Dispatcher --> PluginLoader
    PluginLoader --> CommandRouter
    CommandRouter -->|routes| AdminPlugins
    CommandRouter -->|routes| BotPlugins
    CommandRouter -->|routes| DevPlugins
    CommandRouter -->|routes| MiscPlugins
    CommandRouter -->|routes| ModulePlugins
    CommandRouter -->|routes| PlayPlugins
    CommandRouter -->|routes| SudoPlugins
    CommandRouter -->|routes| ToolsPlugins
    AdminPlugins -->|calls| CallManager
    BotPlugins -->|calls| CallManager
    DevPlugins -->|calls| GitUtils
    MiscPlugins -->|calls| DirUtils
    ModulePlugins -->|calls| MongoWrapper
    PlayPlugins -->|calls| YouTube
    PlayPlugins -->|calls| Spotify
    PlayPlugins -->|calls| SoundCloud
    PlayPlugins -->|calls| Apple
    PlayPlugins -->|calls| Resso
    PlayPlugins -->|calls| Carbon
    PlayPlugins -->|calls| TelegramAdapter
    YouTube -->|"yt-dlp"| YTDLP
    Spotify -->|"yt-dlp"| YTDLP
    SoundCloud -->|"yt-dlp"| YTDLP
    Apple -->|"yt-dlp"| YTDLP
    Resso -->|"yt-dlp"| YTDLP
    Carbon -->|"yt-dlp"| YTDLP
    TelegramAdapter -->|"inline APIs"| TelegramAPI
    CallManager --> PyTgCalls
    PyTgCalls -->|"voice stream"| TelegramAPI
    MongoWrapper -->|reads/writes| MongoDB
    CookieManager -->|stores| CookiesStore
    CookieManager -->|manages cookies| YouTube
    CoreMain -->|uses| CookieManager
    CoreMain -->|uses| GitUtils
    CoreMain -->|uses| DirUtils
    CoreMain -->|uses| MongoWrapper
    CoreMain -->|invoked by| Docker
    CoreMain -->|invoked by| Heroku
    CoreMain -->|invoked by| Render
    CoreMain -->|invoked by| Koyeb
    CICD -->|formats| CoreMain

    %% Click Events
    click BotClient "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/core/bot.py"
    click UserbotClient "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/core/userbot.py"
    click CallManager "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/core/call.py"
    click CookieManager "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/core/cookies.py"
    click GitUtils "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/core/git.py"
    click DirUtils "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/core/dir.py"
    click MongoWrapper "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/core/mongo.py"
    click CoreMain "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/__main__.py"
    click YouTube "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/platforms/Youtube.py"
    click Spotify "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/platforms/Spotify.py"
    click SoundCloud "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/platforms/Soundcloud.py"
    click Apple "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/platforms/Apple.py"
    click Resso "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/platforms/Resso.py"
    click Carbon "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/platforms/Carbon.py"
    click TelegramAdapter "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/platforms/Telegram.py"
    click AdminPlugins "https://github.com/theteamalexa/alexamusic/tree/master/AlexaMusic/plugins/admins"
    click BotPlugins "https://github.com/theteamalexa/alexamusic/tree/master/AlexaMusic/plugins/bot"
    click DevPlugins "https://github.com/theteamalexa/alexamusic/blob/master/AlexaMusic/plugins/devs/dev.py"
    click MiscPlugins "https://github.com/theteamalexa/alexamusic/tree/master/AlexaMusic/plugins/misc"
    click ModulePlugins "https://github.com/theteamalexa/alexamusic/tree/master/AlexaMusic/plugins/modules"
    click PlayPlugins "https://github.com/theteamalexa/alexamusic/tree/master/AlexaMusic/plugins/play"
    click SudoPlugins "https://github.com/theteamalexa/alexamusic/tree/master/AlexaMusic/plugins/sudo"
    click ToolsPlugins "https://github.com/theteamalexa/alexamusic/tree/master/AlexaMusic/plugins/tools"
    click Docker "https://github.com/theteamalexa/alexamusic/tree/master/Dockerfile"
    click CICD "https://github.com/theteamalexa/alexamusic/blob/master/.github/workflows/black.yml"

    %% Styles
    classDef deploy fill:#f0f0f0,stroke:#333
    classDef app fill:#d0eaff,stroke:#339
    classDef core fill:#cce5ff,stroke:#0066cc
    classDef plugin fill:#e6f2ff,stroke:#0059b3
    classDef adapter fill:#e6f2ff,stroke:#0059b3
    classDef external fill:#ccffcc,stroke:#33aa33
    classDef database fill:#ffcccc,stroke:#cc0000
    classDef cookie fill:#ffe5cc,stroke:#cc6600
```
