# celebi-pkg/flight-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/celebi-pkg/flight-analysis
- Repository: https://github.com/celebi-pkg/flight-analysis

## Overview

Flight Analysis is a Python package for collecting Google Flights results, persisting them for historical price tracking, and exposing price and recommendation commands. The principal workflow starts at the CLI or Python API, scrapes flight listings through a Chrome driver, and can save results into SQLite for later queries. Separate components cover analysis, configuration, caching, and legacy implementations. The README documents scheduled scraping, but its workflow implementation was not sampled; source-level edges are limited to shown excerpts and indexed references.

Main entry points: [`src/google_flight_analysis/scrape/scrape.py`](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/scrape.py) (Scrape API), [`src/google_flight_analysis/cli/commands.py`](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/cli/commands.py) (CLI commands), [`src/google_flight_analysis/db/database.py`](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/db/database.py) (Database operations), [`src/google_flight_analysis/scrape/driver.py`](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/driver.py) (Chrome driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Flight CLI<br/>[main.py]"]
  node_cli_commands["CLI commands<br/>[commands.py]"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_scheduled_scraping["Scheduled scraping<br/>[scrape.yml]"]
end

subgraph group_scraping["Flight scraping"]
  node_scrape_api["Scrape API<br/>[scrape.py]"]
  node_flight_extraction["Flight extraction<br/>[scrape.py]"]
  node_chrome_driver["Chrome driver<br/>[driver.py]"]
  node_google_flights["Google Flights"]
  node_browser["Chrome browser"]
end

subgraph group_data["Storage and analysis"]
  node_analysis["Price analysis<br/>[analysis.py]"]
  node_database["Database operations<br/>[database.py]"]
  node_flight_models["Flight data models<br/>[models.py]"]
  node_sqlite[("SQLite database")]
end

subgraph group_support["Configuration and compatibility"]
  node_cache["Scrape cache<br/>[cache.py]"]
  node_configuration["Configuration<br/>[config.py]"]
  node_legacy_scraper["Legacy scraper<br/>[scrape.py]"]
  node_legacy_cache["Legacy cache<br/>[cache.py]"]
  node_legacy_browser["Legacy browser<br/>[chrome_wrapper.py]"]
end

node_user(("User or agent"))

node_user -->|"runs commands"| node_cli
node_user -->|"calls API"| node_python_api
node_cli -->|"dispatches commands"| node_cli_commands
node_cli_commands -->|"starts scrape"| node_scrape_api
node_cli_commands -->|"queries history"| node_database
node_python_api -->|"exposes scrape"| node_scrape_api
node_scrape_api -->|"extracts listings"| node_flight_extraction
node_scrape_api -->|"uses driver"| node_chrome_driver
node_chrome_driver -->|"controls browser"| node_browser
node_browser -.->|"loads flights site"| node_google_flights
node_scrape_api -->|"saves results"| node_database
node_database -->|"queries models"| node_flight_models
node_database -->|"reads and writes"| node_sqlite
node_cli_commands -->|"offers analysis"| node_analysis
node_cli_commands -->|"offers recommendations"| node_analysis
node_configuration -->|"configures driver"| node_chrome_driver
node_configuration -->|"sets database path"| node_database
node_scheduled_scraping -.->|"schedules scraping"| node_scrape_api
node_legacy_scraper -.->|"uses wrapper"| node_legacy_browser

click node_cli "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/cli/main.py"
click node_cli_commands "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/cli/commands.py"
click node_python_api "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/__init__.py"
click node_scrape_api "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/scrape.py"
click node_flight_extraction "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/scrape.py"
click node_chrome_driver "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/driver.py"
click node_analysis "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/analyze/analysis.py"
click node_database "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/db/database.py"
click node_flight_models "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/db/models.py"
click node_cache "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/cache/cache.py"
click node_configuration "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/config.py"
click node_legacy_scraper "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/legacy/scrape.py"
click node_legacy_cache "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/legacy/cache.py"
click node_legacy_browser "https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/legacy/chrome_wrapper.py"
click node_scheduled_scraping "https://github.com/celebi-pkg/flight-analysis/blob/main/.github/workflows/scrape.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cli_commands,node_python_api,node_scheduled_scraping,node_user toneBlue
class node_scrape_api,node_flight_extraction,node_chrome_driver,node_google_flights,node_browser toneAmber
class node_analysis,node_database,node_flight_models,node_sqlite toneMint
class node_cache,node_configuration,node_legacy_scraper,node_legacy_cache,node_legacy_browser toneRose
```

## Components

### User interfaces

- [Flight CLI](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/cli/main.py): `src/google_flight_analysis/cli/main.py`
- [CLI commands](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/cli/commands.py): `src/google_flight_analysis/cli/commands.py`
- [Python API](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/__init__.py): `src/google_flight_analysis/__init__.py`
- [Scheduled scraping](https://github.com/celebi-pkg/flight-analysis/blob/main/.github/workflows/scrape.yml): `.github/workflows/scrape.yml`

### Flight scraping

- [Scrape API](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/scrape.py): `src/google_flight_analysis/scrape/scrape.py`
- [Flight extraction](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/scrape.py): `src/google_flight_analysis/scrape/scrape.py`
- [Chrome driver](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/scrape/driver.py): `src/google_flight_analysis/scrape/driver.py`
- **Google Flights**
- **Chrome browser**

### Storage and analysis

- [Price analysis](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/analyze/analysis.py): `src/google_flight_analysis/analyze/analysis.py`
- [Database operations](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/db/database.py): `src/google_flight_analysis/db/database.py`
- [Flight data models](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/db/models.py): `src/google_flight_analysis/db/models.py`
- **SQLite database**

### Configuration and compatibility

- [Scrape cache](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/cache/cache.py): `src/google_flight_analysis/cache/cache.py`
- [Configuration](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/config.py): `src/google_flight_analysis/config.py`
- [Legacy scraper](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/legacy/scrape.py): `src/google_flight_analysis/legacy/scrape.py`
- [Legacy cache](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/legacy/cache.py): `src/google_flight_analysis/legacy/cache.py`
- [Legacy browser](https://github.com/celebi-pkg/flight-analysis/blob/main/src/google_flight_analysis/legacy/chrome_wrapper.py): `src/google_flight_analysis/legacy/chrome_wrapper.py`

### Other components

- **User or agent**

## Connections

- User or agent → Flight CLI: runs commands (evidence: `README.md`)
- User or agent → Python API: calls API (evidence: `README.md`)
- Flight CLI → CLI commands: dispatches commands (evidence: `src/google_flight_analysis/cli/main.py`)
- CLI commands → Scrape API: starts scrape (evidence: `src/google_flight_analysis/cli/commands.py`)
- CLI commands → Database operations: queries history (evidence: `src/google_flight_analysis/cli/commands.py`)
- Python API → Scrape API: exposes scrape (evidence: `src/google_flight_analysis/__init__.py`)
- Scrape API → Flight extraction: extracts listings (evidence: `src/google_flight_analysis/scrape/scrape.py`)
- Scrape API → Chrome driver: uses driver (evidence: `src/google_flight_analysis/scrape/scrape.py`)
- Chrome driver → Chrome browser: controls browser (evidence: `src/google_flight_analysis/scrape/driver.py`)
- Chrome browser → Google Flights: loads flights site
- Scrape API → Database operations: saves results (evidence: `src/google_flight_analysis/scrape/scrape.py`)
- Database operations → Flight data models: queries models (evidence: `src/google_flight_analysis/db/database.py`)
- Database operations → SQLite database: reads and writes (evidence: `src/google_flight_analysis/db/database.py`)
- CLI commands → Price analysis: offers analysis (evidence: `README.md`)
- CLI commands → Price analysis: offers recommendations (evidence: `README.md`)
- Configuration → Chrome driver: configures driver (evidence: `src/google_flight_analysis/scrape/driver.py`)
- Configuration → Database operations: sets database path (evidence: `src/google_flight_analysis/db/database.py`)
- Scheduled scraping → Scrape API: schedules scraping
- Legacy scraper → Legacy browser: uses wrapper
