# sallywhite-git/frontierwildwatch architecture

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

- Interactive diagram: https://gitdiagram.com/sallywhite-git/frontierwildwatch
- Repository: https://github.com/sallywhite-git/frontierwildwatch

## Overview

FrontierWildWatch plans route-and-date searches, fetches Frontier availability, filters and deduplicates flights, then records run state and can alert on new fares or blocks. The graph separates planning, search execution, Frontier integration, and persistence/notifications. README documents the AI-skill and scheduled-run capabilities; their detailed runtime wiring is not shown in the excerpts, so those links are marked unverified.

Main entry points: [`scanner.py`](https://github.com/sallywhite-git/frontierwildwatch/blob/main/scanner.py) (Scanner runner), [`src/engine/engine.py`](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/engine.py) (Scan engine), [`src/engine/planner.py`](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/planner.py) (Query planner), [`src/engine/fetchers.py`](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/fetchers.py) (Frontier fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Search planning"]
  node_planner["Query planner<br/>[planner.py]"]
  node_airport_data[("Airport data")]
  node_query_models["Query and flight models<br/>[models.py]"]
end

subgraph group_execution["Scan execution"]
  node_scanner["Scanner runner<br/>[scanner.py]"]
  node_engine["Scan engine<br/>[engine.py]"]
  node_event_types["Scan events<br/>[events.py]"]
  node_skill["Agent skill instructions<br/>[SKILL.md]"]
end

subgraph group_frontier["Frontier integration"]
  node_fetcher["Frontier fetcher<br/>[fetchers.py]"]
  node_frontier_client["Mobile API client<br/>[frontier_client.py]"]
  node_frontier_api{{"Frontier mobile API"}}
end

subgraph group_operations["State and alerts"]
  node_state_store[("JSON state store<br/>[state_store.py]")]
  node_notifier_adapter["Notifier adapter<br/>[notifiers.py]"]
  node_telegram_sender["Telegram sender<br/>[notify_telegram.py]"]
  node_telegram{{"Telegram service"}}
end

node_traveler(("Flight-search user"))
node_scheduler(("Cron scheduler"))
node_agent(("AI skill agent"))

node_traveler -->|"runs scans"| node_scanner
node_scheduler -.->|"schedules runs"| node_scanner
node_agent -->|"uses instructions"| node_skill
node_agent -.->|"invokes commands"| node_scanner
node_scanner -->|"plans queries"| node_planner
node_planner -->|"loads airport data"| node_airport_data
node_planner -->|"creates query specs"| node_query_models
node_scanner -->|"runs scan engine"| node_engine
node_engine -->|"fetches queries"| node_fetcher
node_engine -->|"emits events"| node_event_types
node_engine -->|"uses flight models"| node_query_models
node_fetcher -->|"requests outcomes"| node_frontier_client
node_frontier_client -->|"searches availability"| node_frontier_api
node_scanner -->|"loads and saves"| node_state_store
node_scanner -->|"sends alerts"| node_notifier_adapter
node_notifier_adapter -->|"delegates sends"| node_telegram_sender
node_telegram_sender -->|"posts messages"| node_telegram

click node_scanner "https://github.com/sallywhite-git/frontierwildwatch/blob/main/scanner.py"
click node_planner "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/planner.py"
click node_query_models "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/models.py"
click node_engine "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/engine.py"
click node_event_types "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/events.py"
click node_fetcher "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/fetchers.py"
click node_frontier_client "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/frontier_client.py"
click node_state_store "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/state_store.py"
click node_notifier_adapter "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/notifiers.py"
click node_telegram_sender "https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/notify_telegram.py"
click node_skill "https://github.com/sallywhite-git/frontierwildwatch/blob/main/skills/frontier-tracker/SKILL.md"

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_planner,node_airport_data,node_query_models,node_traveler toneBlue
class node_scanner,node_engine,node_event_types,node_skill toneAmber
class node_fetcher,node_frontier_client,node_frontier_api toneMint
class node_state_store,node_notifier_adapter,node_telegram_sender,node_telegram,node_scheduler toneRose
class node_agent toneIndigo
```

## Components

### Search planning

- [Query planner](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/planner.py): `src/engine/planner.py`
- **Airport data**
- [Query and flight models](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/models.py): `src/engine/models.py`

### Scan execution

- [Scanner runner](https://github.com/sallywhite-git/frontierwildwatch/blob/main/scanner.py): `scanner.py`
- [Scan engine](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/engine.py): `src/engine/engine.py`
- [Scan events](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/events.py): `src/engine/events.py`
- [Agent skill instructions](https://github.com/sallywhite-git/frontierwildwatch/blob/main/skills/frontier-tracker/SKILL.md): `skills/frontier-tracker/SKILL.md`

### Frontier integration

- [Frontier fetcher](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/fetchers.py): `src/engine/fetchers.py`
- [Mobile API client](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/frontier_client.py): `src/frontier_client.py`
- **Frontier mobile API**

### State and alerts

- [JSON state store](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/state_store.py): `src/state_store.py`
- [Notifier adapter](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/engine/notifiers.py): `src/engine/notifiers.py`
- [Telegram sender](https://github.com/sallywhite-git/frontierwildwatch/blob/main/src/notify_telegram.py): `src/notify_telegram.py`
- **Telegram service**

### Other components

- **Flight-search user**
- **Cron scheduler**
- **AI skill agent**

## Connections

- Flight-search user → Scanner runner: runs scans (evidence: `README.md`)
- Cron scheduler → Scanner runner: schedules runs (evidence: `README.md`)
- AI skill agent → Agent skill instructions: uses instructions (evidence: `README.md`)
- AI skill agent → Scanner runner: invokes commands (evidence: `README.md`)
- Scanner runner → Query planner: plans queries (evidence: `scanner.py`)
- Query planner → Airport data: loads airport data (evidence: `src/engine/planner.py`)
- Query planner → Query and flight models: creates query specs (evidence: `src/engine/planner.py`)
- Scanner runner → Scan engine: runs scan engine (evidence: `scanner.py`)
- Scan engine → Frontier fetcher: fetches queries (evidence: `src/engine/engine.py`)
- Scan engine → Scan events: emits events (evidence: `src/engine/engine.py`)
- Scan engine → Query and flight models: uses flight models (evidence: `src/engine/engine.py`)
- Frontier fetcher → Mobile API client: requests outcomes (evidence: `src/engine/fetchers.py`)
- Mobile API client → Frontier mobile API: searches availability (evidence: `README.md`)
- Scanner runner → JSON state store: loads and saves (evidence: `scanner.py`)
- Scanner runner → Notifier adapter: sends alerts (evidence: `scanner.py`)
- Notifier adapter → Telegram sender: delegates sends (evidence: `src/engine/notifiers.py`)
- Telegram sender → Telegram service: posts messages (evidence: `src/notify_telegram.py`)