How maryamziya/personal-flight-club works
What this project is (type + purpose)
This is a Python automation/integration service (a small “worker” style app, not a web app) that:
• Reads “watchlist” destination rows + target prices from Google Sheets via Sheety
• Queries Amadeus for flight offers
• Applies parsing/selection logic to find deals (below threshold)
• Sends alerts via Twilio WhatsApp
Repo structure to architecture components
From the file tree + README, each top-level Python module maps cleanly to a logical component/class boundary:
• main.py → Orchestrator / Application entrypoint (control flow)
• data_manager.py → Data access layer for Sheety (destinations + prices; possibly update IATA codes)
• flight_search.py → External API client for Amadeus (auth + search requests)
• flight_data.py → Domain model + selection logic (normalize offers; compute “best” deal)
• notification_manager.py → External API client for Twilio WhatsApp (message composition + send)
Additionally, represent:
• .env / environment variables → Configuration/secret source (runtime dependency)
• External systems: Sheety API (backed by Google Sheets), Amadeus API, Twilio API, WhatsApp network/user handset
There is no explicit database in-repo; Google Sheets is effectively the persistent store.
Main Orchestrator (main.py)
• Loads config from env (dotenv)
For each destination
• main.py → FlightSearch: authenticate (token) + query offers
• flight_search.py → Amadeus API
FlightSearch returns raw offers → FlightData
• flight_data.py parses/normalizes and selects cheapest/best matching itinerary
If price < target
• main.py → NotificationManager
• notification_manager.py → Twilio API → WhatsApp message delivered to user
(Optional/likely pattern in these projects): If IATA codes missing
• main.py → DataManager: update sheet rows with IATA codes via Sheety PUT
Architectural patterns/design principles to highlight (specific to this repo)
• Orchestrator pattern: main.py coordinates workflow, other modules are services/clients.
• Adapter / Gateway pattern for external APIs:
• DataManager = Sheety gateway
• FlightSearch = Amadeus gateway
• NotificationManager = Twilio gateway
• Domain modeling / parsing layer:
• FlightData isolates “interpretation” of Amadeus responses from orchestration.
• Config via environment (12-factor-ish): keys and endpoints are runtime config, not hardcoded.
What to label explicitly (to make it “accurate”)
• Auth mechanism
• Sheety: Bearer token (from env)
• Amadeus: API key/secret → access token (call this out as an auth sub-step if implemented)
• Twilio: SID/Auth Token (from env)
• Data objects
• “Destination rows: {city, IATA, lowestPrice}”
• “Flight offer: {price, outbound date, return date, airline}”
• “Alert message: formatted string with price + route + dates”
• Frequency/trigger
Optional but valuable: include an error/edge-path overlay
• “No deal found” → no notification
• “Missing IATA code” → update Google Sheet row (DataManager PUT)