How turancannb02/telegram-flight-hunter works
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.