# turancannb02/telegram-flight-hunter architecture

> Architecture diagram of the GitHub repository turancannb02/telegram-flight-hunter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/turancannb02/telegram-flight-hunter
- Repository: https://github.com/turancannb02/telegram-flight-hunter

## Overview

##### Project type and purpose
- This is a lightweight, single-process Python “bot” application: a Telegram Flight Hunter.
- Purpose: periodically (and on demand) fetch cheap round-trip flight data from the Amadeus sandbox API and deliver notifications to a user via Telegram.

##### File structure
- Top level only:
- main.py         – contains all bot logic, configuration constants, scheduling and API calls
- .env.example    – template for secrets (Telegram token, chat ID, Amadeus key/secret)
- requirements.txt – lists python-dotenv, python-telegram-bot[asyncio], requests, schedule
- README.md, LICENSE, .gitignore – docs and metadata
- No separate “frontend” or “backend” directories—everything lives in main.py.

##### README for additional insights
- Dependencies & stack: Python 3.10+, python-dotenv, python-telegram-bot for Telegram integration, requests for HTTP, schedule for timed jobs.
- Runtime behavior:
- On startup, loads .env via python-dotenv
- Registers Telegram command handlers (/start, /search)
- Saves chat ID upon /start
- Sets up scheduled jobs (five daytime checks + two nighttime checks)
- Each check: call Amadeus flights API, filter results against thresholds, send Telegram message if criteria met

a. Main components
- Bot Application (main.py)
– Configuration Loader (python-dotenv)
– Command Handler (python-telegram-bot)
– Scheduler (schedule module)
– Flight Search Logic (requests to Amadeus)
– Notification Logic (Telegram API calls)
- External Services
– Telegram Bot API
– Amadeus REST API (sandbox)
- Configuration Store
– .env (TELEGRAM_TOKEN, CHAT_ID, AMA_API_KEY/SECRET)
- Developer / User Actor
– Developer updates constants inside main.py
– End user interacts via Telegram client

b. Relationships and interactions
1. Startup
– Bot reads `.env` → loads secrets/config
– Bot registers handlers with Telegram via python-telegram-bot
2. User Flow
– User sends `/start` → Telegram API delivers Update to Bot
– Bot’s Handler extracts chat ID & persists (in memory or file)
– Bot replies “Started” message via Telegram API
– User sends `/search` → triggers Flight Search Logic
3. Scheduled Flow
– Scheduler triggers Flight Search Logic at configured times
4. Flight Search Logic
– Constructs HTTP request → Amadeus API
– Filters results by PRICE_THRESHOLD, ORIGINS, DESTINATIONS, DATES
– If match → Notification Logic sends message via Telegram API

c. Architectural patterns / design principles
- Single process, modular responsibilities within main.py
- Clear separation:
- Configuration loading
- Input handling (Telegram commands & scheduler)
- Business logic (flight filtering)
- Output (notifications)
- Use of external managed services (Telegram & Amadeus) – no self-hosted infra

d. Key technologies / libraries
- python-dotenv for env management
- python-telegram-bot[asyncio] for Telegram integration
- requests for HTTP calls
- schedule for periodic task scheduling

##### Detail and coverage
- Call out the scheduling times (08:00, 11:00, etc.) or group them under “Scheduled Triggers”.
- Notes on where a developer would modify ORIGINS/DESTINATIONS/DATES constants.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Developer["Developer / User"]:::actor

    %% Configuration Store
    Env((".env")):::config

    %% External Services
    TelegramAPI["Telegram Bot API"]:::external
    AmadeusAPI["Amadeus REST API"]:::external

    %% Bot Application Components
    subgraph "Bot Application"
        ConfigLoader["Configuration Loader"]:::module
        CMD["Command & Scheduler Manager"]:::module
        Scheduler["Scheduler"]:::module
        FS["Flight Search Service"]:::module
        NT["Notification Service"]:::module
    end

    %% Documentation & Metadata
    README["README.md"]:::doc
    LICENSE["LICENSE"]:::doc
    GITIGNORE[".gitignore"]:::doc
    REQ["requirements.txt"]:::doc

    %% Relationships
    Developer -->|"runs bot"| ConfigLoader
    Env -->|"load .env"| ConfigLoader
    ConfigLoader -->|"initialize handlers"| CMD
    CMD -->|"register handlers"| TelegramAPI
    Developer -->|"/start, /search"| TelegramAPI
    TelegramAPI -->|"Update"| CMD
    CMD -->|"on /search"| FS
    CMD -->|"trigger jobs"| Scheduler
    Scheduler -->|"scheduled triggers"| FS
    FS -->|"GET Flights → JSON"| AmadeusAPI
    FS -->|"filter results"| FS
    FS -->|"matches found"| NT
    NT -->|"sendMessage(chat_id, text)"| TelegramAPI

    %% Developer artifacts
    Developer --> README
    Developer --> LICENSE
    Developer --> GITIGNORE
    Developer --> REQ

    %% Click Events
    click ConfigLoader "https://github.com/turancannb02/telegram-flight-hunter/blob/main/main.py"
    click CMD "https://github.com/turancannb02/telegram-flight-hunter/blob/main/main.py"
    click Scheduler "https://github.com/turancannb02/telegram-flight-hunter/blob/main/main.py"
    click FS "https://github.com/turancannb02/telegram-flight-hunter/blob/main/main.py"
    click NT "https://github.com/turancannb02/telegram-flight-hunter/blob/main/main.py"
    click Env "https://github.com/turancannb02/telegram-flight-hunter/blob/main/.env.example"
    click REQ "https://github.com/turancannb02/telegram-flight-hunter/blob/main/requirements.txt"
    click README "https://github.com/turancannb02/telegram-flight-hunter/blob/main/README.md"
    click LICENSE "https://github.com/turancannb02/telegram-flight-hunter/tree/main/LICENSE"
    click GITIGNORE "https://github.com/turancannb02/telegram-flight-hunter/blob/main/.gitignore"

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:2px
    classDef module fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#bfb,stroke:#333,stroke-width:1px
    classDef config fill:#ffb,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef doc fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
