# maryamziya/personal-flight-club architecture

> Architecture diagram of the GitHub repository maryamziya/personal-flight-club, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maryamziya/personal-flight-club
- Repository: https://github.com/maryamziya/personal-flight-club

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% C4 L1 - System Context
%% =========================
subgraph "C4 L1 - System Context"
    direction TB

    U["Traveler / User"]:::actor

    subgraph "Personal Flight Club (Python Worker)"
        direction TB
        SYS["Automation Worker (Scheduled/Triggered Batch Job)"]:::internal
    end

    TRIG["Trigger (Manual run / Cron/Scheduler)"]:::trigger
    ENV["Config & Secrets (ENV/.env via dotenv)"]:::config

    SHEETY["Sheety API (Google Sheets Gateway)"]:::externalApi
    GS[("Google Sheets (Watchlist Store)\nDestinations & Target Prices")]:::datastore

    AMAD["Amadeus Flight Offers API"]:::externalApi

    TW["Twilio Messaging API"]:::externalApi
    WA["WhatsApp Network"]:::externalMsg

    TRIG -->|"starts_run"| SYS
    ENV -->|"provides_keys_tokens_endpoints"| SYS

    SYS <-->|"HTTPS/JSON destinations:{city,IATA,lowestPrice}\nAuth:BearerToken"| SHEETY
    SHEETY <-->|"read/write sheet rows"| GS

    SYS <-->|"HTTPS/JSON flight_search + offers\nAuth:APIKey/Secret→AccessToken"| AMAD

    SYS -->|"HTTPS/JSON send_message\nAuth:TwilioSID+AuthToken"| TW
    TW -.->|"message_delivery"| WA
    WA -.->|"alert_to_user"| U
end

%% =========================
%% C4 L2/L3 - Internal Components & Runtime Flow
%% =========================
subgraph "C4 L2/L3 - Container/Component (Single Run Runtime Flow)"
    direction TB

    TR2["Trigger (Manual run / Cron/Scheduler)"]:::trigger
    ENV2["Config & Secrets (ENV/.env via dotenv)"]:::config

    subgraph "Personal Flight Club (Codebase)"
        direction TB

        MAIN["main.py\nOrchestrator / Control Flow"]:::internal

        subgraph "Adapters / Gateways"
            direction TB
            DM["data_manager.py\nDataManager (Sheety Gateway)"]:::internal
            FS["flight_search.py\nFlightSearch (Amadeus Gateway)"]:::internal
            NM["notification_manager.py\nNotificationManager (Twilio WhatsApp Gateway)"]:::internal
        end

        FD["flight_data.py\nFlightData (Domain Model)\nParse/Normalize + Select Best Deal"]:::internal
    end

    %% External dependencies (reused)
    SHEETY2["Sheety API"]:::externalApi
    GS2[("Google Sheets\n(Persistent Watchlist Store)")]:::datastore
    AMAD2["Amadeus API"]:::externalApi
    TW2["Twilio API"]:::externalApi
    WA2["WhatsApp Network"]:::externalMsg
    U2["Traveler / User"]:::actor

    %% Flow (vertical, orchestrator-centric)
    TR2 -->|"starts_run"| MAIN
    ENV2 -->|"loads_config (dotenv)"| MAIN

    MAIN -->|"GET destinations\nHTTPS/JSON\nAuth:BearerToken"| DM
    DM -->|"request_rows"| SHEETY2
    SHEETY2 <-->|"read/write rows"| GS2
    DM -->|"destination_rows:{city,IATA,lowestPrice}"| MAIN

    MAIN -->|"per_destination:search_params\n(origin,destination,dates)"| FS
    ENV2 -->|"APIKey/Secret"| FS
    FS -->|"auth:APIKey/Secret→access_token"| AMAD2
    FS -->|"HTTPS/JSON flight_offers_query"| AMAD2
    AMAD2 -->|"HTTPS/JSON raw_offers"| FS

    FS -->|"raw_offer_json"| FD
    FD -->|"best_offer:{price,route,dates,airline}"| MAIN

    MAIN -->|"if price < target\ncompose_alert_message"| NM
    ENV2 -->|"TwilioSID/AuthToken"| NM
    NM -->|"HTTPS/JSON send_message"| TW2
    TW2 -.->|"message_delivery"| WA2
    WA2 -.->|"alert"| U2

    %% Edge paths / operational notes
    MAIN -.->|"no_deal_found → no_notification"| MAIN
    MAIN -.->|"missing_IATA_code → PUT row update"| DM
    DM -.->|"PUT row update (IATA)\nHTTPS/JSON"| SHEETY2
end

%% =========================
%% Click events (from component_mapping)
%% =========================
click MAIN "https://github.com/maryamziya/personal-flight-club/blob/main/main.py"
click DM "https://github.com/maryamziya/personal-flight-club/blob/main/data_manager.py"
click FS "https://github.com/maryamziya/personal-flight-club/blob/main/flight_search.py"
click FD "https://github.com/maryamziya/personal-flight-club/blob/main/flight_data.py"
click NM "https://github.com/maryamziya/personal-flight-club/blob/main/notification_manager.py"

%% Bonus: documentation node for click (kept outside main flows to avoid clutter)
DOC["README (Docs: usage/architecture notes)"]:::doc
click DOC "https://github.com/maryamziya/personal-flight-club/blob/main/README.md"

%% =========================
%% Styles (color)
%% =========================
classDef internal fill:#1f6feb,stroke:#0b2f6b,color:#ffffff,stroke-width:1.5px
classDef externalApi fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1.5px
classDef datastore fill:#1f9d55,stroke:#0f5132,color:#ffffff,stroke-width:1.5px
classDef config fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.5px
classDef actor fill:#111827,stroke:#000000,color:#ffffff,stroke-width:1.5px
classDef trigger fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:1.5px
classDef externalMsg fill:#334155,stroke:#0f172a,color:#ffffff,stroke-width:1.5px
classDef doc fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.5px
```
