# dennisfaucher/flightstatus architecture

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

- Interactive diagram: https://gitdiagram.com/dennisfaucher/flightstatus
- Repository: https://github.com/dennisfaucher/flightstatus

## Overview

Flight Status is a self-hosted tracker: a user adds a flight and local departure date, the Flask app fetches and normalizes flight data, then a background worker refreshes it, tracks changes, and sends alerts. Users view and manage their own flights through a polled dashboard. The README documents adaptive refresh, budget limits, cleanup, login, and email behavior; source excerpts show provider lookup, normalization, and alert components. Some worker and route details are unsampled, so their connections rely on README statements.

Main entry points: [`app.py`](https://github.com/dennisfaucher/flightstatus/blob/main/app.py) (Flight management API), [`providers.py`](https://github.com/dennisfaucher/flightstatus/blob/main/providers.py) (Provider lookup and normalization), [`static/app.js`](https://github.com/dennisfaucher/flightstatus/blob/main/static/app.js) (Dashboard interaction), [`mailer.py`](https://github.com/dennisfaucher/flightstatus/blob/main/mailer.py) (SMTP delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Web browser"]
  node_dashboard["Flight dashboard<br/>[index.html]"]
  node_login["Login page<br/>[login.html]"]
  node_frontend["Dashboard interaction<br/>[app.js]"]
end

subgraph group_tracking["Flight tracking"]
  node_app["Flask application<br/>[app.py]"]
  node_auth["User access<br/>[app.py]"]
  node_flight_api["Flight management API<br/>[app.py]"]
  node_worker["Refresh and cleanup<br/>[app.py]"]
  node_state[("Flight state file<br/>[app.py]")]
  node_providers["Provider lookup and normalization<br/>[providers.py]"]
end

subgraph group_alerts["Alerts"]
  node_alerts["Change detection and rendering<br/>[alerts.py]"]
  node_mailer["SMTP delivery<br/>[mailer.py]"]
end

subgraph group_integrations["External services"]
  node_aeroapi["FlightAware AeroAPI"]
  node_airframes["airframes.io fallback"]
  node_smtp["SMTP server"]
end

node_user(("Tracker user"))

node_user -->|"uses"| node_browser
node_browser -->|"opens"| node_dashboard
node_browser -->|"signs in"| node_login
node_dashboard -->|"loads"| node_frontend
node_frontend -->|"requests flights"| node_flight_api
node_frontend -->|"adds, refreshes, removes"| node_flight_api
node_user -->|"authenticates"| node_auth
node_auth -->|"restricts access"| node_flight_api
node_flight_api -->|"looks up flight"| node_providers
node_worker -->|"fetches updates"| node_providers
node_providers -->|"queries"| node_aeroapi
node_providers -.->|"falls back"| node_airframes
node_worker -->|"reads and writes"| node_state
node_worker -->|"checks changes; renders alerts"| node_alerts
node_app -->|"runs refresh worker"| node_worker
node_app -->|"serves endpoints"| node_flight_api
node_app -->|"provides login"| node_auth
node_app -->|"wires alert delivery"| node_mailer
node_mailer -->|"sends email"| node_smtp
node_alerts -.->|"formats messages for"| node_mailer

click node_dashboard "https://github.com/dennisfaucher/flightstatus/blob/main/templates/index.html"
click node_login "https://github.com/dennisfaucher/flightstatus/blob/main/templates/login.html"
click node_frontend "https://github.com/dennisfaucher/flightstatus/blob/main/static/app.js"
click node_app "https://github.com/dennisfaucher/flightstatus/blob/main/app.py"
click node_auth "https://github.com/dennisfaucher/flightstatus/blob/main/app.py"
click node_flight_api "https://github.com/dennisfaucher/flightstatus/blob/main/app.py"
click node_worker "https://github.com/dennisfaucher/flightstatus/blob/main/app.py"
click node_state "https://github.com/dennisfaucher/flightstatus/blob/main/app.py"
click node_providers "https://github.com/dennisfaucher/flightstatus/blob/main/providers.py"
click node_alerts "https://github.com/dennisfaucher/flightstatus/blob/main/alerts.py"
click node_mailer "https://github.com/dennisfaucher/flightstatus/blob/main/mailer.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_browser,node_dashboard,node_login,node_frontend,node_user toneBlue
class node_app,node_auth,node_flight_api,node_worker,node_state,node_providers toneAmber
class node_alerts,node_mailer toneMint
class node_aeroapi,node_airframes,node_smtp toneRose
```

## Components

### Web experience

- **Web browser**
- [Flight dashboard](https://github.com/dennisfaucher/flightstatus/blob/main/templates/index.html): `templates/index.html`
- [Login page](https://github.com/dennisfaucher/flightstatus/blob/main/templates/login.html): `templates/login.html`
- [Dashboard interaction](https://github.com/dennisfaucher/flightstatus/blob/main/static/app.js): `static/app.js`

### Flight tracking

- [Flask application](https://github.com/dennisfaucher/flightstatus/blob/main/app.py): `app.py`
- [User access](https://github.com/dennisfaucher/flightstatus/blob/main/app.py): `app.py`
- [Flight management API](https://github.com/dennisfaucher/flightstatus/blob/main/app.py): `app.py`
- [Refresh and cleanup](https://github.com/dennisfaucher/flightstatus/blob/main/app.py): `app.py`
- [Flight state file](https://github.com/dennisfaucher/flightstatus/blob/main/app.py): `app.py`
- [Provider lookup and normalization](https://github.com/dennisfaucher/flightstatus/blob/main/providers.py): `providers.py`

### Alerts

- [Change detection and rendering](https://github.com/dennisfaucher/flightstatus/blob/main/alerts.py): `alerts.py`
- [SMTP delivery](https://github.com/dennisfaucher/flightstatus/blob/main/mailer.py): `mailer.py`

### External services

- **FlightAware AeroAPI**
- **airframes.io fallback**
- **SMTP server**

### Other components

- **Tracker user**

## Connections

- Tracker user → Web browser: uses (evidence: `README.md`)
- Web browser → Flight dashboard: opens (evidence: `README.md`)
- Web browser → Login page: signs in (evidence: `README.md`)
- Flight dashboard → Dashboard interaction: loads (evidence: `README.md`)
- Dashboard interaction → Flight management API: requests flights (evidence: `static/app.js`)
- Dashboard interaction → Flight management API: adds, refreshes, removes (evidence: `static/app.js`)
- Tracker user → User access: authenticates (evidence: `README.md`)
- User access → Flight management API: restricts access (evidence: `README.md`)
- Flight management API → Provider lookup and normalization: looks up flight (evidence: `app.py`)
- Refresh and cleanup → Provider lookup and normalization: fetches updates (evidence: `README.md`)
- Provider lookup and normalization → FlightAware AeroAPI: queries (evidence: `providers.py`)
- Provider lookup and normalization → airframes.io fallback: falls back (evidence: `README.md`)
- Refresh and cleanup → Flight state file: reads and writes (evidence: `README.md`)
- Refresh and cleanup → Change detection and rendering: checks changes; renders alerts (evidence: `README.md`)
- Flask application → Refresh and cleanup: runs refresh worker (evidence: `README.md`)
- Flask application → Flight management API: serves endpoints (evidence: `README.md`)
- Flask application → User access: provides login (evidence: `README.md`)
- Flask application → SMTP delivery: wires alert delivery (evidence: `README.md`)
- SMTP delivery → SMTP server: sends email (evidence: `mailer.py`)
- Change detection and rendering → SMTP delivery: formats messages for
