# parklez/price-monitor-alerter architecture

> Architecture diagram of the GitHub repository parklez/price-monitor-alerter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parklez/price-monitor-alerter
- Repository: https://github.com/parklez/price-monitor-alerter

## Overview

##### Project Type and Purpose
- Project Type: It is a monitoring and notification application.
- Purpose: The system periodically (hourly) scrapes product prices from several e-commerce websites and logs any changes into a CSV file (prices.csv). It also triggers alerts via a Telegram bot when a price discount is detected.
- Environment: It’s automatically executed via a GitHub Actions workflow, indicating an automated scheduled job rather than a continuously running service.

##### File Structure
- Top-Level Directories/Files:
- .github/workflows: Contains the cronjob.yml file used to schedule the hourly run.
- monitor: This core module holds the main program (main.py) and the scraper utility (scraper.py). The “sites” subdirectory includes individual scraper implementations for different websites (angeloni, dell, goimports, lg, pontofrio).
- monitor/utils: Contains helper modules like safe_writer.py (for handling CSV writes safely) and telegram_notifier.py (for sending alerts).
- docs: Provides the web page and supporting resources (JavaScript and CSS) for historical data analysis.
- tools: Includes auxiliary scripts for tasks (e.g., downloading pages or reading Telegram messages), which could be used for testing or troubleshooting.
- prices.csv: The data store for the logged price changes.
- Configuration Files: .env-example, .gitignore, requirements.txt, and other metadata files suggest clear separation of configuration, code, and documentation.

##### README for Key Insights
- The README highlights critical functions:
- Data Logging: Any price changes are recorded in the CSV file, and GitHub Actions commits these updates.
- Telegram Integration: A notification is sent via a Telegram bot to alert users if a discount is detected.
- Supported Websites: The README explicitly lists the websites for which scraping is implemented, matching the modules in monitor/sites.
- Deployment Setup: Environment variables (like PRODUCTS and TELEGRAM_API_TOKEN) are crucial and are set in the GitHub Actions secrets.

a. Main Components:
- GitHub Actions Scheduler:
- Represents the automation layer that triggers the system on an hourly basis.
- Monitor Engine:
- A “Main Scraper” component (main.py) that orchestrates the overall process.
- Site Scrapers:
- CSV Logger:
- A component labeled “CSV Logger (prices.csv)” that receives data from the monitor engine to record historical price changes.
- Telegram Notifier:
- A module/component for “Telegram Alerts” (using telegram_notifier.py) that is triggered when discounts are detected.
- Utility Tools:
- An optional section representing the “Tools” directory for supporting scripts and testing utilities.
- Historical Data Page:
- A separate component labeled “Docs/Webpage” that represents the visualization of historical data.

b. Relationships and Interactions:

c. Architectural Patterns & Design Principles:
- Modular Design: Each site’s scraper is implemented as its own module (under monitor/sites), making it easy to add or modify scraping rules.
- Separation of Concerns: The system cleanly separates concerns (data scraping, logging, notifying, and visualization).
- Automation & Scheduling: The GitHub Actions workflow is used to periodically trigger the process.
- Extensibility: With separate utilities and tool modules, new features (additional site support, alternative notifications) can be integrated with minimal disruption.

d. Relevant Technologies & Frameworks:
- Python: The programming language used for the monitor’s core logic.
- GitHub Actions: For CI/CD and scheduling.
- Telegram API: For sending bot messages (using the token provided in TELEGRAM_API_TOKEN).
- CSV Files: For simple data storage and logging.
- Web technologies (HTML, JavaScript, CSS): For displaying historical data analysis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Trigger & Scheduler"
        GA["GitHub Actions (Cron Job)"]:::scheduler
    end

    subgraph "Monitor Engine"
        ME["Monitor Engine (main.py)"]:::engine
        SU["Scraper Utility (scraper.py)"]:::utility
    end

    subgraph "Site Scrapers"
        ANG["Angeloni Scraper"]:::scraper
        DEL["Dell Scraper"]:::scraper
        GOI["Goimports Scraper"]:::scraper
        LG["LG Scraper"]:::scraper
        PNT["Pontofrio Scraper"]:::scraper
    end

    CSV["CSV Logger (prices.csv)"]:::database
    TN["Telegram Notifier (telegram_notifier.py)"]:::notifier
    TA["Telegram API"]:::external
    DOC["Historical Data Webpage"]:::docs
    UTIL["Utility Tools"]:::tools

    GA -->|"triggers"| ME
    ME -->|"uses"| SU
    ME -->|"orchestrates"| ANG
    ME -->|"orchestrates"| DEL
    ME -->|"orchestrates"| GOI
    ME -->|"orchestrates"| LG
    ME -->|"orchestrates"| PNT
    ANG -->|"records"| CSV
    DEL -->|"records"| CSV
    GOI -->|"records"| CSV
    LG -->|"records"| CSV
    PNT -->|"records"| CSV
    ME -->|"discount_detected"| TN
    TN -->|"alerts"| TA
    CSV -->|"updates"| DOC
    ME -->|"utilizes"| UTIL

    click GA "https://github.com/parklez/price-monitor-alerter/blob/master/.github/workflows/cronjob.yml"
    click ME "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/main.py"
    click SU "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/scraper.py"
    click ANG "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/sites/angeloni.py"
    click DEL "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/sites/dell.py"
    click GOI "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/sites/goimports.py"
    click LG "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/sites/lg.py"
    click PNT "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/sites/pontofrio.py"
    click CSV "https://github.com/parklez/price-monitor-alerter/blob/master/prices.csv"
    click TN "https://github.com/parklez/price-monitor-alerter/blob/master/monitor/utils/telegram_notifier.py"
    click UTIL "https://github.com/parklez/price-monitor-alerter/tree/master/tools"
    click DOC "https://github.com/parklez/price-monitor-alerter/tree/master/docs"

    classDef scheduler fill:#a0c4ff,stroke:#337ab7,stroke-width:2px;
    classDef engine fill:#caffbf,stroke:#28a745,stroke-width:2px;
    classDef utility fill:#ffdfba,stroke:#ff8c00,stroke-width:2px;
    classDef scraper fill:#ffadad,stroke:#e63946,stroke-width:2px;
    classDef database fill:#fdffb6,stroke:#d4ac0d,stroke-width:2px;
    classDef notifier fill:#bcffbf,stroke:#2a9d8f,stroke-width:2px;
    classDef external fill:#ffd6a5,stroke:#ff4500,stroke-width:2px;
    classDef docs fill:#c3cde6,stroke:#4b0082,stroke-width:2px;
    classDef tools fill:#e0bbff,stroke:#800080,stroke-width:2px;
```
