# pltnk/toptracksbot architecture

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

- Interactive diagram: https://gitdiagram.com/pltnk/toptracksbot
- Repository: https://github.com/pltnk/toptracksbot

## Overview

##### Project type and purpose
- This is a full-stack microservice-style application implementing a Telegram Bot (“Top Tracks Bot”).
- Purpose: fetch the top three tracks of a given artist from Last.fm, get corresponding YouTube videos, cache results in a PostgreSQL database, and serve users on Telegram.

##### File structure
- Top level:
- bot/ – Python source code for the Telegram bot
- db/ – Dockerfile and init.sql for PostgreSQL setup
- tests/ – Dockerfile and pytest suite for validating bot logic and integrations
- docker-compose.yml – service definitions for bot and database (and optional test profile)
- .env_example / .env – environment variable definitions for API keys, DB credentials, caching TTL
- Key patterns:
- Asynchronous I/O (HTTPX, asyncpg, python-telegram-bot async API)
- Clear separation: fetching logic (bot/fetching), processing (bot/processing.py), run/bootstrap scripts (bot/run.py, bot/wait_for_db.py)
- Docker-based deployment with service orchestration

##### Extract README insights
- Main external dependencies: Telegram Bot API, Last.fm API, YouTube Data API v3, PostgreSQL
- Deployment via Docker Compose: two primary containers (bot + DB) plus an ephemeral test container
- Caching strategy: store results in DB for configurable number of days

##### Main components & interactions
a. Components
1. Telegram Client (users on Telegram)
2. Telegram Bot Service (bot container)
- Command Handler (/info, /help)
- Fetching Module: Last.fm client, YouTube client
- Processing Module: parse input, collate APIs, format Telegram responses
- Database Access Layer (asyncpg)
3. PostgreSQL Database (db container)
4. External APIs: Last.fm API, YouTube Data API
b. Relationships & data flow
- User → Telegram API → Bot Service
- Bot Service → Last.fm API → fetch top tracks
- Bot Service → YouTube API → fetch video URLs
- Bot Service ↔ PostgreSQL → cache/retrieve artist data
- Bot Service → Telegram API → send formatted messages
c. Architectural patterns & design principles
- Separation of concerns: fetching, processing, data storage, and bot orchestration are modular
- Asynchronous I/O for external calls to maintain high throughput
- Containerized microservices for isolation and easy scaling
- Test suite runs in isolated container leveraging same codebase and Dockerfile
d. Technologies & frameworks
- python-telegram-bot (async) – Bot framework
- HTTPX – HTTP client for Last.fm and YouTube calls
- asyncpg – Async PostgreSQL client
- Docker & Docker Compose – container orchestration
- pytest – Automated testing

##### Detail
- Command Handler
- Fetching Layer (lastfm.py, youtube.py)
- Processing Layer (processing.py)
- DB Wait & Init (wait_for_db.py)
- Environment variables (.env) feeding into Bot Service: TTBOT_TOKEN, TTBOT_LASTFM_API_KEY, TTBOT_YOUTUBE_API_KEY, caching TTL
- If desired, show how Docker Compose ties together “bot” and “db” services and forwards ports.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    User["User"]:::external
    TelegramAPI["Telegram API"]:::external
    LastfmAPI["Last.fm API"]:::external
    YouTubeAPI["YouTube Data API"]:::external

    %% Docker Compose grouping
    subgraph "Docker Compose" 
        direction TB
        subgraph "Bot Container"
            direction TB
            BotService["Telegram Bot Service"]:::internal
            subgraph "Bot Service Components"
                direction TB
                Run["Entry Point (run.py)"]:::module
                CommandHandler["Command Handler"]:::module
                subgraph "Fetching Layer"
                    direction TB
                    LastfmClient["Last.fm Client"]:::module
                    YouTubeClient["YouTube Client"]:::module
                    FetchUtil["Fetching Utilities"]:::module
                end
                Processing["Processing Module"]:::module
                WaitDB["DB Wait & Init"]:::module
                Config["Config Definitions"]:::module
                Exceptions["Exception Definitions"]:::module
            end
        end
        subgraph "DB Container"
            direction TB
            PostgresDB["PostgreSQL Database"]:::database
        end
    end

    %% Environment
    EnvExample[".env_example"]:::env
    Env[".env"]:::env

    %% Tests & CI
    subgraph "Testing & CI"
        direction TB
        TestsDir["Tests Directory"]:::test
        CIWorkflow["CI Workflow"]:::test
    end

    %% Data Flows
    User -->|"sends message"| TelegramAPI
    TelegramAPI -->|"forwards update"| BotService
    BotService -->|"fetch top tracks"| LastfmAPI
    BotService -->|"fetch video URLs"| YouTubeAPI
    BotService <-->|"cache/retrieve"| PostgresDB
    BotService -->|"send message"| TelegramAPI

    %% Env to BotService
    EnvExample --> BotService
    Env --> BotService

    %% Tests to BotService and DB
    TestsDir --> BotService
    TestsDir --> PostgresDB
    CIWorkflow --> TestsDir

    %% Click Events
    click BotService "https://github.com/pltnk/toptracksbot/tree/main/bot/"
    click Run "https://github.com/pltnk/toptracksbot/blob/main/bot/run.py"
    click LastfmClient "https://github.com/pltnk/toptracksbot/blob/main/bot/fetching/lastfm.py"
    click YouTubeClient "https://github.com/pltnk/toptracksbot/blob/main/bot/fetching/youtube.py"
    click FetchUtil "https://github.com/pltnk/toptracksbot/blob/main/bot/fetching/util.py"
    click Processing "https://github.com/pltnk/toptracksbot/blob/main/bot/processing.py"
    click WaitDB "https://github.com/pltnk/toptracksbot/blob/main/bot/wait_for_db.py"
    click Config "https://github.com/pltnk/toptracksbot/blob/main/bot/config.py"
    click Exceptions "https://github.com/pltnk/toptracksbot/blob/main/bot/exceptions.py"
    click PostgresDB "https://github.com/pltnk/toptracksbot/tree/main/db/"
    click PostgresDB "https://github.com/pltnk/toptracksbot/tree/main/db/Dockerfile"
    click PostgresDB "https://github.com/pltnk/toptracksbot/blob/main/db/init.sql"
    click EnvExample "https://github.com/pltnk/toptracksbot/blob/main/.env_example"
    click Env "https://github.com/pltnk/toptracksbot/blob/main/.env"
    click TestsDir "https://github.com/pltnk/toptracksbot/tree/main/tests/"
    click TestsDir "https://github.com/pltnk/toptracksbot/tree/main/tests/Dockerfile"
    click TestsDir "https://github.com/pltnk/toptracksbot/blob/main/tests/conftest.py"
    click TestsDir "https://github.com/pltnk/toptracksbot/blob/main/tests/test_env_vars.py"
    click TestsDir "https://github.com/pltnk/toptracksbot/blob/main/tests/test_exceptions.py"
    click TestsDir "https://github.com/pltnk/toptracksbot/blob/main/tests/test_lastfm.py"
    click TestsDir "https://github.com/pltnk/toptracksbot/blob/main/tests/test_processing.py"
    click TestsDir "https://github.com/pltnk/toptracksbot/blob/main/tests/test_wait_for_db.py"
    click TestsDir "https://github.com/pltnk/toptracksbot/blob/main/tests/test_youtube.py"
    click CIWorkflow "https://github.com/pltnk/toptracksbot/blob/main/.github/workflows/run-tests.yml"
    click CIWorkflow "https://github.com/pltnk/toptracksbot/blob/main/docker-compose.yml"

    %% Styles
    classDef external fill:#E8F0FE,stroke:#1E3A8A,color:#1E3A8A;
    classDef internal fill:#D1FAE5,stroke:#065F46,color:#065F46;
    classDef database fill:#FEF3C7,stroke:#92400E,color:#92400E;
    classDef module fill:#F0F9FF,stroke:#0369A1,color:#0369A1;
    classDef env fill:#F3E8FF,stroke:#6B21A8,color:#6B21A8;
    classDef test fill:#FEE2E2,stroke:#B91C1C,color:#B91C1C;
```
