# aweirddev/flights architecture

> Architecture diagram of the GitHub repository aweirddev/flights, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aweirddev/flights
- Repository: https://github.com/aweirddev/flights

## Overview

fast-flights is a Python Google Flights scraper/API. The principal workflow builds a typed flight query, encodes it for Google Flights, fetches results through the default or an optional integration, and parses HTML/embedded JavaScript into structured itineraries. SearchApi is a separate data-source integration with richer result types. The SearchApi excerpt is partial, so its detailed request and dispatch wiring is not inferred.

Main entry points: [`fast_flights/fetcher.py`](https://github.com/aweirddev/flights/blob/dev/fast_flights/fetcher.py) (get_flights), [`fast_flights/parser.py`](https://github.com/aweirddev/flights/blob/dev/fast_flights/parser.py) (HTML/JS parser), [`fast_flights/integrations/bright_data.py`](https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/bright_data.py) (Bright Data adapter), [`fast_flights/integrations/searchapi.py`](https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/searchapi.py) (SearchApi adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query modeling"]
  node_create_query["Create query<br/>[querying.py]"]
  node_query_model["Query model<br/>[querying.py]"]
  node_protobuf["Protobuf schema<br/>[flights.proto]"]
  node_flights_pb["Protobuf classes<br/>[flights_pb2.py]"]
end

subgraph group_runtime["Search runtime"]
  node_get_flights["get_flights<br/>[fetcher.py]"]
  node_default_fetch["Default fetch<br/>[fetcher.py]"]
  node_parser["HTML/JS parser<br/>[parser.py]"]
end

subgraph group_integrations["Integrations"]
  node_integration_base["Integration interfaces<br/>[base.py]"]
  node_bright_data["Bright Data adapter<br/>[bright_data.py]"]
  node_searchapi["SearchApi adapter<br/>[searchapi.py]"]
end

subgraph group_results["Result modeling"]
  node_result_list["Parsed itineraries<br/>[parser.py]"]
  node_result_models["Flight data models<br/>[model.py]"]
  node_search_result["Rich search results<br/>[searchapi.py]"]
end

node_user(("Library caller"))
node_google{{"Google Flights"}}
node_bright_service{{"Bright Data service"}}
node_search_service{{"SearchApi service"}}

node_user -->|"specifies search"| node_create_query
node_create_query -->|"builds query"| node_query_model
node_query_model -->|"creates messages"| node_flights_pb
node_flights_pb -->|"implements schema"| node_protobuf
node_user -->|"requests flights"| node_get_flights
node_get_flights -->|"fetches by default"| node_default_fetch
node_default_fetch -->|"requests search page"| node_google
node_default_fetch -->|"reads URL parameters"| node_query_model
node_default_fetch -->|"passes HTML"| node_parser
node_parser -->|"builds flight objects"| node_result_models
node_parser -->|"returns itineraries"| node_result_list
node_get_flights -->|"dispatches integrations"| node_integration_base
node_bright_data -->|"implements fetch interface"| node_integration_base
node_bright_data -.->|"posts page request"| node_bright_service
node_get_flights -.->|"uses optional fetcher"| node_bright_data
node_searchapi -->|"maps rich response"| node_search_result
node_searchapi -.->|"queries flight data"| node_search_service
node_get_flights -.->|"uses optional data source"| node_searchapi
node_get_flights -.->|"returns data-source result"| node_search_result

click node_create_query "https://github.com/aweirddev/flights/blob/dev/fast_flights/querying.py"
click node_query_model "https://github.com/aweirddev/flights/blob/dev/fast_flights/querying.py"
click node_protobuf "https://github.com/aweirddev/flights/blob/dev/fast_flights/pb/flights.proto"
click node_flights_pb "https://github.com/aweirddev/flights/blob/dev/fast_flights/pb/flights_pb2.py"
click node_get_flights "https://github.com/aweirddev/flights/blob/dev/fast_flights/fetcher.py"
click node_default_fetch "https://github.com/aweirddev/flights/blob/dev/fast_flights/fetcher.py"
click node_parser "https://github.com/aweirddev/flights/blob/dev/fast_flights/parser.py"
click node_result_list "https://github.com/aweirddev/flights/blob/dev/fast_flights/parser.py"
click node_result_models "https://github.com/aweirddev/flights/blob/dev/fast_flights/model.py"
click node_integration_base "https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/base.py"
click node_bright_data "https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/bright_data.py"
click node_searchapi "https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/searchapi.py"
click node_search_result "https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/searchapi.py"

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_create_query,node_query_model,node_protobuf,node_flights_pb toneBlue
class node_get_flights,node_default_fetch,node_parser toneAmber
class node_integration_base,node_bright_data,node_searchapi,node_search_service toneMint
class node_result_list,node_result_models,node_search_result toneRose
class node_user,node_google,node_bright_service toneIndigo
```

## Components

### Query modeling

- [Create query](https://github.com/aweirddev/flights/blob/dev/fast_flights/querying.py): `fast_flights/querying.py`
- [Query model](https://github.com/aweirddev/flights/blob/dev/fast_flights/querying.py): `fast_flights/querying.py`
- [Protobuf schema](https://github.com/aweirddev/flights/blob/dev/fast_flights/pb/flights.proto): `fast_flights/pb/flights.proto`
- [Protobuf classes](https://github.com/aweirddev/flights/blob/dev/fast_flights/pb/flights_pb2.py): `fast_flights/pb/flights_pb2.py`

### Search runtime

- [get_flights](https://github.com/aweirddev/flights/blob/dev/fast_flights/fetcher.py): `fast_flights/fetcher.py`
- [Default fetch](https://github.com/aweirddev/flights/blob/dev/fast_flights/fetcher.py): `fast_flights/fetcher.py`
- [HTML/JS parser](https://github.com/aweirddev/flights/blob/dev/fast_flights/parser.py): `fast_flights/parser.py`

### Integrations

- [Integration interfaces](https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/base.py): `fast_flights/integrations/base.py`
- [Bright Data adapter](https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/bright_data.py): `fast_flights/integrations/bright_data.py`
- [SearchApi adapter](https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/searchapi.py): `fast_flights/integrations/searchapi.py`

### Result modeling

- [Parsed itineraries](https://github.com/aweirddev/flights/blob/dev/fast_flights/parser.py): `fast_flights/parser.py`
- [Flight data models](https://github.com/aweirddev/flights/blob/dev/fast_flights/model.py): `fast_flights/model.py`
- [Rich search results](https://github.com/aweirddev/flights/blob/dev/fast_flights/integrations/searchapi.py): `fast_flights/integrations/searchapi.py`

### Other components

- **Library caller**
- **Google Flights**
- **Bright Data service**
- **SearchApi service**

## Connections

- Library caller → Create query: specifies search
- Create query → Query model: builds query
- Query model → Protobuf classes: creates messages
- Protobuf classes → Protobuf schema: implements schema
- Library caller → get_flights: requests flights
- get_flights → Default fetch: fetches by default
- Default fetch → Google Flights: requests search page
- Default fetch → Query model: reads URL parameters
- Default fetch → HTML/JS parser: passes HTML
- HTML/JS parser → Flight data models: builds flight objects
- HTML/JS parser → Parsed itineraries: returns itineraries
- get_flights → Integration interfaces: dispatches integrations
- Bright Data adapter → Integration interfaces: implements fetch interface
- Bright Data adapter → Bright Data service: posts page request
- get_flights → Bright Data adapter: uses optional fetcher
- SearchApi adapter → Rich search results: maps rich response
- SearchApi adapter → SearchApi service: queries flight data
- get_flights → SearchApi adapter: uses optional data source
- get_flights → Rich search results: returns data-source result