API Library Overview

AeroCopilot is built to live alongside the existing tools pilots already use, rather than replace them. Every external system the app talks to is grouped into one of nine categories below — each can be reasoned about, rate-limited, retried, and revoked independently.

The integrations layer (apps/web/lib/integrations/ for OAuth-credentialed clients, apps/web/app/api/cron/ for scheduled data ingestion, apps/web/app/api/map/ for on-demand proxies) keeps every connection narrow and audited.

1. User-credentialed integrations

Each user opts in individually. We hold the OAuth refresh token (encrypted at rest) and access the upstream on the user's behalf, with a hardcoded read-only method whitelist.

• MyFlightbook — OAuth2 logbook sync. Pulls flights, aircraft, currency, and totals. Read-only against the live MFB site by design; write methods are blocked at the client.
• Google OAuth — sign-in via Better Auth.

2. Flight services (FAA-contracted)

• Leidos FFSP — File / retrieve / amend / activate / cancel / close flight plans, plus standard route briefings, area briefings, and route search. HTTP Basic auth with vendor-issued credentials. Returns { available: false } when credentials are not yet configured so the rest of the app stays operational.

3. Aeronautical data pipelines (FAA family)

Scheduled ingestion of FAA-published reference data on the cadence FAA actually publishes it. Each one is an independent cron job; failures are isolated.

• NASR (National Airspace System Resources) — 28-day cycle. Airports, runways, frequencies, navaids. Source: nfdc.faa.gov.
• CIFP (Coded Instrument Flight Procedures) — 1st & 15th of month, AIRAC-aligned. Procedures, fixes, holds, navaids. Source: aeronav.faa.gov.
• FAA Chart Products (Wave 2 self-tile pipeline) — Weekly per family (Sectional Mon, TAC Tue, Helicopter Wed, Caribbean / Grand Canyon Thu, IFR Low Fri, IFR High Sat). Downloads primary GeoTIFFs, tiles them with GDAL, uploads to Cloudflare R2.
• AD (Airworthiness Directives) — Daily. Source: adx.faa.gov.
• AD historic backfill — Weekly Sunday. Catches up on legacy records.
• Aircraft Registry — Monthly. N-number lookup. Source: registry.faa.gov.
• FAA Airman (CTI dataset) — Monthly 6th. Pilot certificate roster. Source: av-info.faa.gov.
• DOF (Digital Obstacle File) — Bi-monthly (1st & 15th 06:00 UTC). Towers, transmission lines, antennas. Parser implemented (~500 lines, ZIP discovery + DMS conversion + multi-candidate URL fallback). Required by the helicopter Synthetic Vision 7-day freshness gate.
• Airspace / Airways — Bi-monthly (1st & 15th 05:00 UTC), AIRAC-aligned. Class B/C/D shelves, MOAs, restricted areas, Victor / Jet airways. Source: FAA-hosted ArcGIS feature services.
• UASFM — Monthly. UAS Facility Maps for drone airspace grid.
• Obstacle sync — Monthly (1st 06:00 UTC). Per-tile obstacle ingestion, complementary to DOF.
• Repair Stations / Flight Schools / Part 135 Operators — Monthly. Source: av-info.faa.gov.
• NAS Status — Every 5 min. Ground stops, delays. Source: nasstatus.faa.gov.
• TFRs — Every 10 min. Source: FAA NOTAM Search.
• NOTAMs — Every 10 min. ICAO-format NOTAM batches.
• D-ATIS — Every 10 min. Digital ATIS broadcasts. Source: datis.clowd.io.
• Weather Cameras — Every 6 hours. Source: weathercams.faa.gov.

4. Weather (NOAA / NWS / AviationWeather.gov)

The aviation-weather backbone. Most are pure ingestion (METAR / TAF go straight into Postgres); a few are tile or alert layers.

• METAR every 5 min, TAF every 30 min, PIREP every 15 min — Source: aviationweather.gov.
• SIGMET / G-AIRMET every 15 min and 3 hrs.
• Center Weather Advisories (CWA) every 15 min.
• International SIGMETs every 15 min.
• Convective Outlooks every 2 hrs.
• Forecast Discussions every 3 hrs (NWS WFO output).
• MIS (Meteorological Impact Statements) every 30 min.
• Winds Aloft every 6 hrs.
• MOS (Model Output Statistics) every 6 hrs. Source: Iowa Environmental Mesonet.
• Smoke (NOAA HMS) every 3 hrs. Wildfire smoke plumes.
• AQI (EPA AirNow) hourly.
• Space Weather (NOAA SWPC) hourly. CMEs, geomagnetic storms.
• SPC Watches & Mesoscale every 15 min. Severe-weather watches and outlooks.
• Tropical (NHC) every 3 hrs. Active tropical cyclones.
• NWS Alerts every 5 min. Flood, hurricane, tornado, etc.
• CO-OPS Tides + NOAA NDBC Buoys — Marine met for coastal ops.
• NavCanada METAR / TAF every 30 min — for cross-border IFR / VFR.
• Tile health every 30 min — probes upstream availability.

5. Hazards (USGS / FEMA / NASA)

On-demand and scheduled ingest of geographic hazards relevant to flight planning.

• USGS Earthquakes — earthquake.usgs.gov. On-demand via /api/map/hazards, also referenced in /api/hazards/route-check.
• USGS Volcanoes — volcanoes.usgs.gov.
• USGS Elevation (3DEP / EPQS) — epqs.nationalmap.gov. On-demand via /api/elevation/point and /api/elevation/profile.
• NASA FIRMS Wildfires — firms.modaps.eosdis.nasa.gov.
• FEMA Hazards — hazards.fema.gov.

6. Live traffic & operations

• OpenSky Network ADS-B — opensky-network.org. Live (where licensed) ADS-B traffic. Polled via adsb-sync cron.
• FlightAware AeroAPI — aeroapi.flightaware.com. Per-flight tracking + flight-plan retrieval.
• SWIM (FAA System Wide Information Management) — A separate Railway service streams FAA SWIM messages (Flight Plans, NOTAMs, ITWS, terminal weather) into our internal /api/swim/*/ingest endpoints over the Railway internal network.

7. Drone airspace (LAANC)

• Aloft USS LAANC — api.aloft.ai. Submit and poll Low Altitude Authorization and Notification Capability requests. The defensive laanc-status-poll cron picks up submitted rows older than 30s and asks Aloft directly, in case the webhook callback was lost.

8. Other public datasets

• NTSB Accident Reports — Historical safety data via NTSB AvData MDB weekly ingest (Sundays 05:00 UTC). Source: https://data.ntsb.gov/avdata/avall.zip (~94 MB, refreshed 1st/8th/15th/22nd of each month). Pipeline: download ZIP → unzip → mdb-export to CSV → join events + aircraft tables → upsert AccidentReport rows by eventId. Requires mdbtools system binary (provisioned in railpack.json); when missing, the cron completes with noopReason: 'mdb_tools_not_installed' so the admin dashboard surfaces "Awaiting infra" rather than a silent failure. The legacy CAROL JSON API was retired by NTSB in 2025; the AvData MDB is the canonical replacement per the NTSB Open Data Plan 2025-2026 (developer.ntsb.gov is the future API surface but currently sign-up-gated).
• eBird — api.ebird.org. Bird-strike risk by region (intended for FRAT / route planning).
• Tomorrow.io — api.tomorrow.io. Tactical hyper-local weather, on-demand.
• OpenStreetMap Nominatim — nominatim.openstreetmap.org. Geocoding for airport / waypoint search.
• Federal Register + GAO RSS — federalregister.gov, gao.gov. The newsroom Tier 1 RSS monitor pulls regulatory + accountability feeds for editorial pipeline.
• OurAirports OSS dataset — ourairports.com. Bootstrap data for airports outside NASR.

9. Platform infrastructure (operational)

These are not pilot-facing, but they keep the lights on.

• Stripe — Billing, dunning, subscription lifecycle.
• Anthropic Claude — api.anthropic.com. AI copilot inference.
• PostHog — Product analytics, opt-in via consent banner.
• Sentry — Error tracking on web + cron-worker.
• Resend — Transactional email (account, dunning, vermont confirm, renewal reminder).
• Healthchecks.io — hc-ping.com. Per-cron ping endpoints, gated on HEALTHCHECKS_PING_URL_<JOB> env vars.
• Cloudflare R2 — Chart tile storage (Cloudflare R2 / Tigris S3-compatible).

Cross-cutting concerns

Every integration in the library follows the same operational rules:

• server-only — All clients begin with import 'server-only'; so credentials and tokens never reach the browser bundle.
• Token encryption — Long-lived OAuth refresh tokens are encrypted with AES-256-GCM via crypto.ts before being written to the IntegrationToken table.
• Rate limiting — Where the upstream provider asks for it (MyFlightbook asks for ~500 ms between calls), the client enforces it in code rather than trusting the caller.
• Graceful degradation — Where credentials are optional (Leidos, NTSB), the client returns a structured { available: false } or noopReason: env_not_configured instead of throwing, so the UI can render a clear "not configured" state.
• Method-level safety guards — Where the upstream API can mutate shared data (MFB aircraft are shared between pilots), the client enforces a hardcoded whitelist of allowed methods.
• Internal self-fetch — Cron triggers and admin "Run Now" use RAILWAY_PRIVATE_DOMAIN (Railway internal network) rather than the public hostname, bypassing the edge layer that historically rejected /api/cron/* GETs with 405.
• Sync job tracking — Every scheduled ingestion writes a sync_job row that the admin Sync Central dashboard surfaces with status, duration, and noopReason metadata when no records were synced.
• Circuit breakers + resilient retry — Available as withCircuitBreaker and withResilientRetry. Coverage is being lifted from the current per-route opt-in to a default for every third-party-API route.

Roadmap — known gaps

The following pilot-value integrations are not yet in the library and would require dedicated work:

• ForeFlight account sync — Today only the Release Packet email is supported; full account sync is on the roadmap.
• Garmin Pilot / flyGarmin — Comparison pages exist; no API integration yet.
• CloudAhoy debrief import — Comparison page exists; no API.
• SkyVector route import — Comparison page exists; no API.
• ADS-B receiver direct ingest (Stratus / Sentry / Garmin GDL) — Only OpenSky network polling exists today.
• NTSB replacement source — CAROL JSON API retired; AvData CSV ingestion is the next candidate.
• DOF env-var setup + full ingestion — The freshness gate on helicopter Synthetic Vision is in place; the underlying ingest is a stub awaiting FAA_DOF_DATA_URL.
• d-TPP approach plates + SID/STAR plates — Coded CIFP procedures are ingested; the visual approach plates and graphical departure / arrival diagrams are not yet pulled from FAA d-TPP.
• Equipment-aware NOTAM filtering — Bulk NOTAMs are ingested; per-aircraft equipment-relevant filtering (e.g. WAAS-out at alternate during 1-2-3 evaluation) is roadmap.

Related

• MyFlightbook Logbook Sync
• Leidos FAA Briefing Service
• Signing In with Google