# albertopasqualetto/amazon-deals-telegram-bot architecture

> Architecture diagram of the GitHub repository albertopasqualetto/amazon-deals-telegram-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albertopasqualetto/amazon-deals-telegram-bot
- Repository: https://github.com/albertopasqualetto/amazon-deals-telegram-bot

## Overview

##### Project type and purpose
- This is a specialized automation tool: a Telegram bot that scrapes deals from the Italian Amazon page and posts them to a Telegram channel.
- Its purpose is to automatically retrieve deal data via web scraping (using Selenium and chromedriver) and then format and send that data as messages through Telegram’s API. The bot utilizes caching (storing product IDs) to avoid repeated scraping within a short time.

##### File structure and key components
- Top-Level files:
- .env.example holds configuration details (e.g., Telegram bot token).
- Dockerfile and docker-compose.yml indicate containerization and easy deployment options.
- requirements.txt for dependencies (likely Selenium, Python libraries, etc.).
- The core logic is inside the amazon-deals-telegram-bot directory:
- __main__.py is the entry point that initiates scraping and triggers the Telegram messaging.
- amazon_page_analyser.py contains the code for scraping Amazon web pages, extracting deals and product IDs.
- test_ids.py suggests there are tests to validate which products should be selected.
- The presence of Docker configurations hints that the system is designed to be deployed in a containerized environment, possibly in conjunction with Selenium Grid (as noted in the README for server deployment).

a. Components:
- Telegram Bot Module – the interface that communicates with the Telegram Bot API.
- Web Scraper Component – represented by amazon_page_analyser.py, which performs the scraping of Amazon’s website.
- Data/State Management – represents caching of product IDs and state handling (note: IDs are cached to avoid re-selection within two hours).
- Configuration/Environment Handler – using the .env file for critical information (bot token, channel settings, etc.).
- Selenium/Chromedriver Module – interaction with Chrome (or Chromium) to perform headless browsing and scraping.
- Deployment Container – Dockerfile and docker-compose setup that may include a Selenium node/grid if deploying on a server.
b. Relationships and Interactions:
- The main execution flow (in __main__.py) initializes configuration by reading the environment variables.
- It then triggers the web scraper to extract deal information from Amazon via Selenium.
- Once a valid deal is identified (ensuring it is not a recently used ID), the Telegram Bot Module formats and sends a message to the designated Telegram channel.
- The caching mechanism ensures that repeated deals are not resent.
- For server deployment, an additional container using Docker Compose and Selenium Grid nodes may be incorporated to handle the scraping load.
c. Architectural Patterns & Design Principles:
- Separation of Concerns – Isolate scraping, messaging, and configuration.
- Modularity – The core functionalities are segmented into separate scripts for easier maintainability and testing.
- Containerization – Deployment leverages Docker to wrap the entire system, which adds portability and simplifies environment management.
d. Technologies and Libraries:
- Python (as the main programming language).
- Selenium for browser automation.
- Chromedriver for controlled Chrome/Chromium browsing.
- Telegram Bot API library to interact with Telegram.
- Docker and Docker Compose for containerized deployment.
- (Possibly) cron jobs for scheduling message send-outs, as suggested in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Deployment Cluster
    subgraph "Configuration & Deployment"
        ConfigLoader["Configuration Loader (.env)"]:::config
        subgraph "Deployment Container"
            Dockerfile["Dockerfile"]:::container
            DockerCompose["docker-compose.yml"]:::container
        end
    end

    %% Scraping Cluster
    subgraph "Scraping Cluster"
        AmazonScraper["Amazon Scraper (amazon_page_analyser.py)"]:::module
        Selenium["Selenium/Chromedriver Module"]:::external
    end

    %% Messaging Cluster
    subgraph "Messaging Cluster"
        MainOrchestrator["Main Orchestrator (Telegram Bot Module)"]:::module
        TelegramAPI["Telegram Bot API Connector"]:::external
    end

    %% Additional External Component for Containerized Deployment
    SeleniumGrid["Selenium Grid Node"]:::external

    %% Data Flow Connections
    ConfigLoader -->|"loads"| AmazonScraper
    ConfigLoader -->|"loads"| MainOrchestrator
    Dockerfile -->|"manages"| SeleniumGrid
    SeleniumGrid -->|"provides"| Selenium
    AmazonScraper -->|"scrapesDeals"| Selenium
    AmazonScraper -->|"sendsDealData"| MainOrchestrator
    MainOrchestrator -->|"sendsMessage"| TelegramAPI

    %% Click Events
    click ConfigLoader "https://github.com/albertopasqualetto/amazon-deals-telegram-bot/blob/main/.env.example"
    click Dockerfile "https://github.com/albertopasqualetto/amazon-deals-telegram-bot/tree/main/Dockerfile"
    click DockerCompose "https://github.com/albertopasqualetto/amazon-deals-telegram-bot/blob/main/docker-compose.yml"
    click MainOrchestrator "https://github.com/albertopasqualetto/amazon-deals-telegram-bot/blob/main/amazon-deals-telegram-bot/__main__.py"
    click AmazonScraper "https://github.com/albertopasqualetto/amazon-deals-telegram-bot/blob/main/amazon-deals-telegram-bot/amazon_page_analyser.py"

    %% Styles
    classDef module fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef external fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef config fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef container fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
```
