Flyfun Weather
Medium-range aviation weather assessment for cross-country GA flights in Europe
🌍 weather.flyfun.aero — live web app · 📱 iOS / iPadOS app
The Python package and module are named weatherbrief; the product is Flyfun Weather.
Flyfun Weather fetches forecast data from multiple numerical weather prediction (NWP) models, performs aviation-specific analysis (icing, turbulence, convection, clouds), and presents everything side-by-side so pilots can compare models and start forming an early view of what conditions will look like from D-7 through D-0.
Disclaimer — Flyfun Weather is built to help and support flight planning and decision-making, giving pilots an early, multi-model picture of the weather and surfacing the factors that matter for a route. It relies on automated analysis and AI, which can make mistakes or miss things, and it has not been reviewed by a professional meteorologist. It is not a substitute for official weather briefings, MET reports, or professional meteorological advice. Always consult official sources before flying — the pilot in command remains the sole decision-maker. The app is a free hobby project provided as is, and no liability is accepted for its use — see TERMS.md.
What it does
- Multi-model forecasting — Fetches 6 NWP models via Open-Meteo (GFS, ECMWF IFS, DWD ICON, UKMO, Meteo-France, Best Match) at up to 28 pressure levels along your route, with high-resolution GRIB2 enrichment (upper-air soundings, cloud microphysics) direct from ECMWF IFS, DWD ICON-EU, and NOAA GFS where coverage allows
- ~85 derived metrics — From raw NWP data, derives thermodynamic indices (CAPE, CIN, Lifted Index, K-Index, etc.), cloud layers, icing zones (multiple methods), CAT turbulence risk, convective potential, wind shear, and more using MetPy
- 20+ route advisories across 11 categories — Deterministic hazard evaluators (icing incl. freezing precipitation, cloud, en-route visibility/precipitation, turbulence incl. wave-corroborated mountain wind, convective incl. terminal convective & LLWS, winds-aloft trip impact, airport conditions incl. density altitude, feasibility, model quality, fronts, sun/daylight) with per-model GREEN/AMBER/RED severity grading and worst/majority aggregation
- D-0 observations — METAR/TAF for departure/arrival airports plus route SIGMETs (area hazards), with a deterministic banner flagging conditions that have worsened since the last refresh
- Weather-based alternates — When a destination is marginal (D-2 inward), surfaces nearby divert candidates that fix the deficient axis (category/wind/crosswind), classified before/after along the route, plus a regulatory "is an alternate required?" estimate (FAA 14 CFR 91.169 + EASA Part-NCO)
- Model comparison — Side-by-side divergence scoring so you can see where models agree and where they don't
- Interactive cross-section — Canvas-rendered visualization with ~25 toggleable layers (terrain, clouds, icing, SFIP, CAT, inversions, convective, temperature lines, stability levels, NWP cloud bands), switchable themes, a compare-across-models mode, and hover/click interaction
- Route map & route graph — Leaflet route map with an altitude slider and metric-colored segments (incl. an "alternate required?" mode), plus a scalar route graph sharing the cross-section's x-axis
- Skew-T soundings — Per-waypoint, per-model diagrams: a dynamic canvas Skew-T with a multi-variable side panel and overlay bands, a multi-model compare mode, and the classic MetPy PNG (CAPE/CIN shading, hodograph, indices panel)
- GRAMET cross-section — From the Autorouter API (requires credentials)
- LLM-powered synopsis — Optional AI-generated weather narrative via Claude or ChatGPT, combining DWD synoptic text with quantitative analysis; beyond the high-resolution horizon it switches to a cheaper, confidence-led
Weather Models
| Model | Source | Forecast range |
|---|
| Best Match | Open-Meteo auto-select | 16 days |
| ECMWF IFS | European Centre | 10 days |
| GFS | NOAA (US) | 16 days |
| DWD ICON | German Weather Service | 7 days |
| UKMO | UK Met Office | 7 days |
| Meteo-France | Meteo-France Arpege | 6 days |
Not all variables are available from all models (e.g., omega/vertical velocity is missing from ICON and Meteo-France, visibility from ECMWF). Flyfun Weather derives fallbacks where possible and clearly indicates when data is unavailable.
Route Advisories
Each advisory evaluates a specific weather hazard along your route, per model. The set has grown to 20+ evaluators across 11 categories; a representative selection:
| Advisory | What it checks |
|---|
| Icing Escape | Can you descend below freezing to escape icing? (terrain clearance) |
| FIKI Icing | Icing layer thickness and severity for FIKI-equipped aircraft |
| Freezing Level | Freezing level vs terrain (mountain icing risk) |
| Freezing Precipitation | Freezing rain / ice pellets in the column |
| Cloud Top | Can you fly above the clouds? (cloud top vs flight ceiling) |
| VMC Cruise | Cloud coverage at cruise altitude (VFR viability) |
| En-route Visibility | Visibility and precipitation along the route |
| VFR / IFR Feasibility | Overall VFR/IFR viability vs ceiling, visibility, and cloud layers |
| Flight Category | VFR/MVFR/IFR/LIFR classification at departure, en-route, and arrival |
| Turbulence | Clear Air Turbulence + strong vertical motion at cruise |
| Mountain Wind | Orographic/rotor wind risk near significant terrain (wave-corroborated) |
| Winds Aloft | Headwind/tailwind trip impact along the route |
| Airport Conditions | Surface wind, gusts, crosswind, and density altitude at departure/arrival |
| Terminal Convective / LLWS | Low-level wind shear and convective risk near the airports |
| Convective | Thunderstorm development risk from CAPE and instability indices |
| Fronts | Frontal passages crossing the route |
| Sun | Daylight / sun position relative to the flight window |
| Model Agreement | How much do the models agree with each other? |
Advisory parameters are user-tunable (terrain margins, percentage thresholds, etc.) and can be recalculated without re-fetching weather data.
Tech Stack
Backend: Python 3.11+ / FastAPI / Pydantic v2 / SQLAlchemy + Alembic / MetPy / Matplotlib / LangChain+LangGraph / FastMCP
Frontend: TypeScript / Vanilla DOM (no framework) / Zustand / Canvas API / Leaflet / esbuild
iOS / iPadOS: Swift / SwiftUI / Xcode
Infrastructure: Docker / SQLite (dev) / MySQL (prod) / Multi-provider OAuth (Google, Apple)
Testing: pytest (~5,000 tests) / vitest / Playwright / Swift Testing (iOS unit tests) — all gated by CI on every push and PR
Project Structure
src/weatherbrief/
├── models/ # Pydantic v2 data models
├── pipeline.py # Core engine: fetch → analyze → outputs
├── tasks/ # Independently runnable pipeline stages (fetch, analyze, advise, …)
├── fetch/ # Data retrieval (Open-Meteo, GRIB2 enrichment, SRTM, GRAMET, DWD text)
├── analysis/
│ ├── wind.py # Headwind/crosswind decomposition
│ ├── comparison.py # Multi-model divergence scoring
│ ├── advisories/ # 20+ route hazard evaluators (registry pattern)
│ └── sounding/ # MetPy thermodynamic analysis (clouds, icing, CAT, convective)
├── frontal/ # Frontal zone detection
├── hewson/ # Hewson θe diagnostic field precompute (NPZ snapshots)
├── era5/ # ERA5 reanalysis loaders for retrospective calibration
├── digest/ # Text digest, Skew-T plots, LLM briefing (LangGraph)
├── api/ # FastAPI app (auth, flights, packs, preferences, admin)
├── mcp/ # MCP server exposing briefings as AI-assistant tools
├── connectors/ # Shared agent-facing response shaping (MCP + GPT/OpenAPI)
├── db/ # SQLAlchemy ORM + Alembic migrations
├── storage/ # File-based artifact persistence
├── report/ # HTML/PDF rendering (Jinja2 + WeasyPrint)
├── notify/ # Email delivery + push notifications
├── verify/ # Forecast verification vs METAR/TAF (collect, stats, digest, archive)
├── debriefs/ # Post-flight pilot judgement capture
├── analytics/ # Privacy-first usage analytics
├── costs.py # Cost ledger / spend tracking
├── eval_workbench/ # Dev-only golden-labelling workbench for the LLM digest eval
├── scenario/ # Scenario previews ("where/when could I fly") — measurement harness
├── triage/ # AI-assisted feedback triage CLI
└── release/ # Release-notes / What's New CLI
web/
├── ts/
│ ├── visualization/ # Canvas cross-section renderer (~25 layers)
│ ├── store/ # Zustand state management
│ ├── managers/ # DOM rendering (briefing, advisories, flights)
│ ├── adapters/ # API communication
│ ├── i18n/ # Locale bundles (en, fr, de, es)
│ └── data/ # Metrics catalog, display config
├── tests/ # Playwright e2e specs + vitest unit tests
├── css/style.css
├── index.html # Flights list
├── briefing.html # Briefing report (collapsible sections)
├── flight.html # Single flight detail / edit
├── maps.html # Pan-European forecast map
├── verification.html # Forecast verification / model skill (admin)
├── pireps.html # Pilot reports
├── settings.html # User preferences + advisory tuning
├── admin.html # User approval + usage tracking
├── login.html # Authentication page
├── help.html # User help / FAQ + What's New
├── donate.html # Optional support / donations (Stripe)
├── privacy.html # Privacy policy
├── eval.html # LLM digest eval workbench (dev/admin)
├── cost-summary.html # Service cost transparency (admin)
└── user-costs.html # Personal usage & cost tracking
app/flyfun-weather/ # Native iOS / iPadOS app (SwiftUI, Xcode project)
configs/ # LLM digest configuration and prompts
designs/ # Design documentation (see designs/INDEX.md)
tests/ # pytest test suite (~5,000 tests)
alembic/versions/ # Database migrations
Getting Started
Prerequisites
- Python 3.11+ (CI runs 3.13)
- Node.js 22+ (for frontend build)
- SQLite (development) or MySQL (production)
Installation
# Clone the repository
git clone https://github.com/roznet/flyfun-weather.git
cd flyfun-weather
# Create virtual environment
python -m venv venv
source venv/bin/activate
# Install Python dependencies
pip install -e ".[dev]"
# Install frontend dependencies and build
cd web
npm install
npm run build
cd ..
Environment Variables
Copy .env.sample to .env in the project root and fill in what you need.
The essentials:
ENVIRONMENT=development
# Optional — for LLM-powered digest
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
# Optional — for GRAMET cross-sections (Autorouter account)
AUTOROUTER_USERNAME=...
AUTOROUTER_PASSWORD=...
# Required for production multi-user deployment
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
JWT_SECRET=...
CREDENTIAL_ENCRYPTION_KEY=...
DATABASE_URL=mysql+pymysql://...
In development mode, the app uses SQLite and auto-creates a dev user — no OAuth setup needed.
Running
Web app (development):
# Start the API server
uvicorn weatherbrief.api.app:app --reload --port 8000
# In another terminal — watch and rebuild frontend
cd web && npm run dev
Then open http://localhost:8000
MCP server (AI-assistant tools):
python -m weatherbrief.mcp
Other operational entry points follow the same pattern — python -m weatherbrief.verify
(forecast verification), python -m weatherbrief.hewson (frontal diagnostic precompute),
python -m weatherbrief.release (What's New stream). Each prints its own usage.
Testing
The full suite runs in CI on every push and PR (see the badge above); to run it locally:
# Python — ~5,000 tests. `-m 'not slow'` is applied by default via pyproject
source venv/bin/activate
pytest
# Frontend typecheck, build and unit tests
cd web
npx tsc --noEmit
npm run build
npx vitest run
# End-to-end (boots the API server itself; needs the venv at the repo root)
npx playwright install --with-deps chromium
npx playwright test
# iOS unit tests, run from the repo root (the block above leaves you in web/).
# The UI tests are excluded here, as they are in CI: they drive a simulator and are
# run manually.
xcodebuild test \
-project app/flyfun-weather/flyfun-weather.xcodeproj \
-scheme flyfun-weather \
-destination 'platform=iOS Simulator,name=iPhone 17,OS=latest' \
-only-testing:flyfun-weatherTests
CI is split across two workflows, path-filtered so they don't overlap.
.github/workflows/tests.yml runs three parallel jobs —
pytest, typecheck + build + vitest, and playwright — and
.github/workflows/ios.yml runs the iOS unit tests on a
macOS runner. A commit touching app/ runs the iOS job, anything else runs the
server/web jobs, and a commit spanning both runs both. Commits touching only
designs/, .claude/ or Markdown skip CI entirely.
Docker
docker build -t weatherbrief .
docker compose up -d
The Docker image runs as a non-root user (UID 2000). Data is persisted via volume mount at /app/data.
Data Sources
- NWP forecasts — Open-Meteo (free, open-source weather API), plus high-resolution GRIB2 enrichment direct from ECMWF IFS, DWD ICON-EU, and NOAA GFS where available
- METAR / TAF & SIGMETs — NOAA Aviation Weather Center for day-of observations, terminal forecasts, and route SIGMETs
- Terrain elevation — SRTM 90m resolution via srtm.py
- Airport database — euro-aip (European AIP data)
- Navigation waypoints — Eurocontrol FRA, OpenNav, OurAirports NAVAIDs, and FAA NASR (free public sources; ~95,900 deduplicated points on the 28-day AIRAC/NASR cycle)
- GRAMET cross-sections — Autorouter (requires free account)
- Synoptic text forecasts — DWD (German Weather Service) open data; NWS Area Forecast Discussions for US routes
How the Analysis Works
The pipeline fetches NWP data for ~20 interpolated points along your route (every ~20nm), plus your departure/arrival airports. For each point and model, it runs a MetPy-based sounding analysis that computes:
- Thermodynamic indices — CAPE (surface, most-unstable, mixed-layer), CIN, Lifted Index, K-Index, Total Totals, Showalter Index
- Cloud layers — detected from dewpoint depression at pressure levels, classified by coverage (SCT/BKN/OVC)
- Icing zones — using the Ogimet continuous icing index (physically peaks at -7C matching observed supercooled liquid water), with type classification (clear/mixed/rime) from temperature bands
- CAT turbulence — Richardson number from Brunt-Vaisala frequency and wind shear, classified NONE/LIGHT/MODERATE/SEVERE
- Convective risk — from CAPE thresholds with CIN modulation and severe weather modifiers (shear, hail indicators)
- Vertical motion — omega profiles classified as quiescent, synoptic ascent/subsidence, oscillating, or convective
These per-point results feed into the 20+ route-level advisory evaluators that produce the GREEN/AMBER/RED hazard assessment.
Known Limitations
- Not a certified weather product — this is an exploratory tool for understanding NWP data
- Vertical resolution varies by model — GFS resolves 28 pressure levels (~25 hPa spacing in the lower atmosphere), but ECMWF offers only 13 via Open-Meteo, so thin cloud layers can still be missed on the coarser models
- No ensemble data — currently uses deterministic runs only (except precipitation probability from GFS/ECMWF)
- European focus — airport database and some features (DWD text, Autorouter GRAMET) are Europe-centric
- NWP cloud vs sounding cloud — two independent cloud detection methods can disagree (see design docs for details)
Design Documentation
The designs/ directory contains detailed design documents covering architecture, data models, analysis methods, metrics catalog, and implementation plans. Start with designs/architecture.md for the system overview, or designs/INDEX.md for the full module map.
AI Acknowledgment
This project was built extensively with AI assistance. Claude (Anthropic) was used throughout development for:
- Architecture design and implementation planning
- Weather analysis algorithms and metric derivations
- Aviation-specific threshold selection and advisory logic
- Frontend visualization (canvas rendering, interaction patterns)
- Code implementation across the full stack
The meteorological explanations, threshold values, and aviation interpretations in the codebase were developed collaboratively with AI. While cross-referenced against published references (MetPy documentation, Ogimet/Autorouter formulas, standard aviation weather texts), they have not been reviewed by a professional meteorologist.
The optional LLM-powered weather digest feature uses Claude or ChatGPT to generate narrative briefings from the quantitative analysis.
License
MIT
Contributing
This is an early-stage personal project. Issues and discussions are welcome. If you're a meteorologist or aviation weather professional and spot something wrong, please open an issue — corrections are very much appreciated.
If you're sending a pull request, the test suite gates every PR — running
pytest and the web checks locally first will save you a round trip. Migrations must
work on both SQLite (dev) and MySQL (prod); use batch_alter_table for any ALTER.
