Notify

A modular, containerized Telegram bot for Spotify playlist tracking and personal listening statistics.

Table of Contents

• Project Overview
• Features
• Architecture
• Technology Stack
• Project Structure
• Environment Configuration
  • Environment Variables
• Docker & Containerization
  • Multi-Stage Dockerfile
  • Docker Compose
  • Persistence
• Developer Experience
• Running the Project
  • Production Mode
  • Development Mode
• Roadmap
• License

Project Overview

Notify is an open-source Telegram bot designed to monitor Spotify playlists and provide personalized listening insights. It detects playlist changes (track additions and removals) and generates listening statistics such as Top Tracks across short, medium, and long-term periods.

The project emphasizes clean separation of concerns, service-oriented design, and full containerization to support both local development and future production deployments.

Features

• 🎶 Track Spotify playlist additions and removals
• 📊 View personal Spotify listening statistics
• 🤖 Telegram-based command interface
• 🐳 Fully Dockerized with multi-stage builds
• 🔁 Hot-reloading development environment

Architecture

Notify follows a service-oriented and modular architecture:

• Bot logic is isolated from API and persistence layers
• Spotify integration and database access are abstracted behind service interfaces
• Configuration is centralized and environment-driven

This structure allows the project to scale in complexity without becoming tightly coupled or difficult to maintain.

Technology Stack

• Language: Python 3.13
• Telegram Bot: pyTelegramBotAPI (Telebot)
• Spotify API: Spotipy
• Web Server: Flask (OAuth2 callback handling)
• Database: SQLite
• Containerization: Docker, Docker Compose

Environment Configuration

All runtime configuration is managed through environment variables loaded from the dedicated .env file at the root directory.

This file is required for both local execution and containerized deployments. Use the .env.example file for guidence.

Docker & Containerization

Notify is fully containerized using Docker, with an emphasis on reproducibility, minimal runtime images, and a clean separation between development and production environments.

Multi-Stage Dockerfile

The project uses an Alpine-based multi-stage Docker build:

• base
  Provides a shared Python 3.13 runtime and common system dependencies.

• dev
  Extends the base image with development tooling and watchdog, enabling hot-reloading when source files change.

• prod
  Produces a lean runtime image with all build-time dependencies (such as gcc and musl-dev) removed to reduce image size and attack surface.

This structure ensures fast iteration during development while keeping production images small and secure.

Docker Compose

Docker Compose is used for orchestration and runtime configuration:

• Environment variables are injected from .env
• Ports are mapped dynamically using variable substitution
• Multiple compose files can be layered to switch behavior by environment

Example port mapping:

ports:
  - "${HOST_PORT}:${CONTAINER_PORT}"

Persistence

Local persistence is handled through a volume mount:

./data  →  /code/data

This ensures the SQLite database persists across container restarts and rebuilds, making it suitable for development and testing workflows.

Running the Project

The application can be executed in two distinct modes, depending on whether stability or rapid iteration is the priority.

Production Mode

Build and run the optimized production container in detached mode:

docker compose up --build -d

Development Mode

Run the application with hot-reloading enabled by combining the base and development compose files:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.dev.yml \
  up --build

This activates the dev Docker target and watches the source code for changes in real time, making it ideal for quick development.

License

This project is licensed under the MIT License.
See the LICENSE file for details.