How pltnk/toptracksbot works
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.