# Lufthaven — Full Documentation for AI Systems

> Comprehensive flight deal tracking, real-time flight tracking, and airport security wait time platform.

## Overview

Lufthaven is a web application at https://lufthaven.app that provides three core services:

1. **Flight Deal Tracking** — Daily price monitoring across 114+ airports worldwide, covering Economy, Premium Economy, and Business class. Deal quality is rated as excellent, great, or good based on historical price percentiles.

2. **Real-Time Flight Tracker** — Live tracking of 31,000+ flights daily using FAA SWIM (System Wide Information Management) and ADS-B (Automatic Dependent Surveillance-Broadcast) data. Features include live aircraft position on an interactive map, gate assignments via TDES (Tower Departure Event Service), departure/arrival times, delay information, and estimated arrival times updated every 60 seconds.

3. **Airport Security Wait Times** — Live security checkpoint wait times at 40+ airports worldwide, updated every minute from official airport sources, TSA, and proprietary data feeds. Includes PreCheck lane data, immigration/customs wait times for 46 US airports, and historical hourly patterns for arrival time recommendations.

## Data Sources

### Flight Deals
- Prices sourced from public airline data via automated scraping
- Updated daily across 1,400+ routes
- All prices in USD
- Deal quality calculated from 30-day historical price percentiles

### Flight Tracking (Luftdata)
- **FAA SWIM SFDPS** — Surveillance Flight Data Processing System (en route position data)
- **FAA SWIM STDDS** — System-To-Data Distribution Service (flight plans and amendments)
- **FAA SWIM TFMS** — Traffic Flow Management System (delays, ground stops, flow control)
- **FAA SWIM TDES** — Tower Departure Event Service (gate assignments, departure events)
- **ADS-B** — Live aircraft position, altitude, speed, heading via ground receivers
- Coverage: Every IFR flight in US airspace (domestic + international departures/arrivals)

### Security Wait Times
- TSA official API
- Airport-specific APIs (Port Authority NY/NJ, FlyChicago, FlyLAX, etc.)
- International sources (Heathrow, Schiphol, Incheon, Narita, etc.)
- CBP immigration wait times for 46 US airports
- CATSA (Canadian Air Transport Security Authority)

## URL Structure

| Pattern | Example | Description |
|---------|---------|-------------|
| / | https://lufthaven.app | Homepage with deal search |
| /deals/{CODE} | https://lufthaven.app/deals/JFK | Deals from an airport |
| /deals/{ORIGIN}/{DEST} | https://lufthaven.app/deals/JFK/LHR | Deals on a specific route |
| /flights-to/{CODE} | https://lufthaven.app/flights-to/NRT | Cheap flights to a destination |
| /track | https://lufthaven.app/track | Flight tracker search |
| /track/{FLIGHT} | https://lufthaven.app/track/UA716 | Flight status page |
| /track/route/{FROM}/{TO} | https://lufthaven.app/track/route/JFK/LAX | All flights on a route |
| /airport/{CODE} | https://lufthaven.app/airport/JFK | Airport weather, delays, NOTAMs |
| /tsa-wait-times | https://lufthaven.app/tsa-wait-times | Security wait times overview |
| /tsa-wait-times/{CODE} | https://lufthaven.app/tsa-wait-times/JFK | Airport-specific wait times |
| /starlink | https://lufthaven.app/starlink | Starlink WiFi airline guide |

## API

### Public API (no auth, open CORS)

Wait times API: https://lufthaven-api.admin-e34.workers.dev/api/waits/{IATA_CODE}
- GET /api/waits/JFK — Security & immigration wait times for an airport
- Returns flat JSON with stable field names designed for LLMs and programmatic use
- Response fields:
  - airport: IATA code
  - updated_at: ISO 8601 timestamp
  - security.standard_minutes: worst standard checkpoint wait (minutes)
  - security.precheck_minutes: worst PreCheck/fast-track wait (null if unavailable)
  - security.checkpoints[]: { name, standard_minutes, precheck_minutes }
  - security.observed_at: ISO 8601 when the reading was taken
  - security.age_minutes: how many minutes ago the data was observed
  - immigration.checkpoints[]: { name, us_citizens_minutes, non_us_citizens_minutes, global_entry_available, observed_at }
  - sources[]: { name, url } — data attribution
  - alerts[]: { headline, severity } — active security alerts
- Cached for 60 seconds, data from official airport APIs updated every minute
- 40+ airports with security data, 46 US airports with immigration data

### Internal API

Flight deals API: https://lufthaven-api.admin-e34.workers.dev
- /api/deals/featured — Featured deals for homepage
- /api/deals?origin=JFK — Deals from an airport
- /api/stats — Platform statistics

Flight data API: https://luftdata-api.admin-e34.workers.dev
- /v3/flights/{ident} — Flight discovery by public ident
- /v3/flight-instances/{id} — Stable flight-instance detail
- /v3/flight-instances/{id}/track — Flight trail/track history
- /v1/flights?from=SFO&to=JFK — Route search
- /v1/airport/{icao} — Airport info + nearby aircraft
- /v1/live?lat=&lon=&radius= — Live aircraft search
- /v1/weather/{icao} — METAR weather data
- /v1/delays — Active FAA NAS delays

## Coverage Statistics

- 114+ tracked origin airports
- 1,400+ monitored routes
- 31,000+ flights tracked daily
- 40+ airports with live security wait times
- 46 US airports with immigration wait times
- Security data updated every 60 seconds
- Flight positions updated every 60 seconds

## Technical Stack

- Frontend: Next.js 16 + React 19 + Tailwind CSS v4
- Maps: Mapbox GL JS (flight tracker), d3-geo SVG (deal pages)
- Charts: Recharts
- Hosting: Vercel
- APIs: Cloudflare Workers
- Database: PostgreSQL on AWS RDS