# shahrzad-2004/flight-assistant architecture

> Architecture diagram of the GitHub repository shahrzad-2004/flight-assistant, 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/shahrzad-2004/flight-assistant
- Repository: https://github.com/shahrzad-2004/flight-assistant

## Overview

flight-assistant is a Streamlit flight-ticket assistant. The main workflow is a user entering flight details through chat and UI controls, the flight graph processing state and requesting flight searches, and the app presenting sortable results. The repository also includes Google sign-in and persistent user-owned chat sessions. The README is brief and several central modules were not sampled, so links involving their internal orchestration are omitted where source evidence is unavailable.

Main entry points: [`app.py`](https://github.com/shahrzad-2004/flight-assistant/blob/main/app.py) (Streamlit app), [`authentication.py`](https://github.com/shahrzad-2004/flight-assistant/blob/main/authentication.py) (Google authentication), [`flight_scraper/scraper_manager.py`](https://github.com/shahrzad-2004/flight-assistant/blob/main/flight_scraper/scraper_manager.py) (Scraper manager), [`ui_handlers.py`](https://github.com/shahrzad-2004/flight-assistant/blob/main/ui_handlers.py) (UI callbacks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Chat and UI"]
  node_app["Streamlit app<br/>[app.py]"]
  node_handlers["UI callbacks<br/>[ui_handlers.py]"]
  node_graph["Flight conversation graph<br/>[flight_graph.py]"]
  node_responses["Chat responses<br/>[chat_response.py]"]
end

subgraph group_flight["Flight search"]
  node_matching["City matching<br/>[city_matching.py]"]
  node_logic["Flight logic<br/>[flight_logic.py]"]
  node_manager["Scraper manager<br/>[scraper_manager.py]"]
  node_domestic["Domestic scrapers"]
  node_international["International scrapers"]
  node_worker["Browser executor"]
  node_state["Flight state models<br/>[models.py]"]
end

subgraph group_identity["Identity and storage"]
  node_auth["Google authentication<br/>[authentication.py]"]
  node_cookies["Cookie manager<br/>[cookie_manager.py]"]
  node_users[("User database<br/>[user_database.py]")]
  node_chatdb[("Chat database<br/>[chat_database.py]")]
end

subgraph group_integrations["External services"]
  node_google(("Google identity"))
  node_airlines(("Airline booking sites"))
end

node_traveler(("Traveler"))

node_traveler -->|"enters flight request"| node_app
node_app -->|"dispatches UI actions"| node_handlers
node_handlers -->|"invokes graph"| node_graph
node_app -->|"lists sessions"| node_chatdb
node_handlers -->|"saves messages"| node_chatdb
node_app -->|"handles sign-in"| node_auth
node_auth -->|"exchanges OAuth data"| node_google
node_auth -->|"creates account"| node_users
node_auth -->|"stores user ID"| node_cookies
node_manager -->|"gets executor"| node_worker
node_manager -->|"dispatches domestic search"| node_domestic
node_manager -->|"dispatches international search"| node_international
node_domestic -->|"scrapes flight listings"| node_airlines
node_international -->|"scrapes flight listings"| node_airlines

click node_app "https://github.com/shahrzad-2004/flight-assistant/blob/main/app.py"
click node_handlers "https://github.com/shahrzad-2004/flight-assistant/blob/main/ui_handlers.py"
click node_graph "https://github.com/shahrzad-2004/flight-assistant/blob/main/flight_graph.py"
click node_responses "https://github.com/shahrzad-2004/flight-assistant/blob/main/chat_response.py"
click node_matching "https://github.com/shahrzad-2004/flight-assistant/blob/main/city_matching.py"
click node_logic "https://github.com/shahrzad-2004/flight-assistant/blob/main/flight_logic.py"
click node_manager "https://github.com/shahrzad-2004/flight-assistant/blob/main/flight_scraper/scraper_manager.py"
click node_domestic "https://github.com/shahrzad-2004/flight-assistant/tree/main/flight_scraper"
click node_international "https://github.com/shahrzad-2004/flight-assistant/tree/main/flight_scraper"
click node_worker "https://github.com/shahrzad-2004/flight-assistant/blob/main/playwright_worker.py"
click node_state "https://github.com/shahrzad-2004/flight-assistant/blob/main/models.py"
click node_auth "https://github.com/shahrzad-2004/flight-assistant/blob/main/authentication.py"
click node_cookies "https://github.com/shahrzad-2004/flight-assistant/blob/main/cookie_manager.py"
click node_users "https://github.com/shahrzad-2004/flight-assistant/blob/main/user_database.py"
click node_chatdb "https://github.com/shahrzad-2004/flight-assistant/blob/main/chat_database.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_app,node_handlers,node_graph,node_responses toneBlue
class node_matching,node_logic,node_manager,node_domestic,node_international,node_worker,node_state toneAmber
class node_auth,node_cookies,node_users,node_chatdb toneMint
class node_google,node_airlines toneRose
class node_traveler toneIndigo
```

## Components

### Chat and UI

- [Streamlit app](https://github.com/shahrzad-2004/flight-assistant/blob/main/app.py): `app.py`
- [UI callbacks](https://github.com/shahrzad-2004/flight-assistant/blob/main/ui_handlers.py): `ui_handlers.py`
- [Flight conversation graph](https://github.com/shahrzad-2004/flight-assistant/blob/main/flight_graph.py): `flight_graph.py`
- [Chat responses](https://github.com/shahrzad-2004/flight-assistant/blob/main/chat_response.py): `chat_response.py`

### Flight search

- [City matching](https://github.com/shahrzad-2004/flight-assistant/blob/main/city_matching.py): `city_matching.py`
- [Flight logic](https://github.com/shahrzad-2004/flight-assistant/blob/main/flight_logic.py): `flight_logic.py`
- [Scraper manager](https://github.com/shahrzad-2004/flight-assistant/blob/main/flight_scraper/scraper_manager.py): `flight_scraper/scraper_manager.py`
- [Domestic scrapers](https://github.com/shahrzad-2004/flight-assistant/tree/main/flight_scraper): `flight_scraper`
- [International scrapers](https://github.com/shahrzad-2004/flight-assistant/tree/main/flight_scraper): `flight_scraper`
- [Browser executor](https://github.com/shahrzad-2004/flight-assistant/blob/main/playwright_worker.py): `playwright_worker.py`
- [Flight state models](https://github.com/shahrzad-2004/flight-assistant/blob/main/models.py): `models.py`

### Identity and storage

- [Google authentication](https://github.com/shahrzad-2004/flight-assistant/blob/main/authentication.py): `authentication.py`
- [Cookie manager](https://github.com/shahrzad-2004/flight-assistant/blob/main/cookie_manager.py): `cookie_manager.py`
- [User database](https://github.com/shahrzad-2004/flight-assistant/blob/main/user_database.py): `user_database.py`
- [Chat database](https://github.com/shahrzad-2004/flight-assistant/blob/main/chat_database.py): `chat_database.py`

### External services

- **Google identity**
- **Airline booking sites**

### Other components

- **Traveler**

## Connections

- Traveler → Streamlit app: enters flight request
- Streamlit app → UI callbacks: dispatches UI actions
- UI callbacks → Flight conversation graph: invokes graph
- Streamlit app → Chat database: lists sessions
- UI callbacks → Chat database: saves messages
- Streamlit app → Google authentication: handles sign-in
- Google authentication → Google identity: exchanges OAuth data
- Google authentication → User database: creates account
- Google authentication → Cookie manager: stores user ID
- Scraper manager → Browser executor: gets executor
- Scraper manager → Domestic scrapers: dispatches domestic search
- Scraper manager → International scrapers: dispatches international search
- Domestic scrapers → Airline booking sites: scrapes flight listings
- International scrapers → Airline booking sites: scrapes flight listings