AeroScope Documentation

Live aircraft tracking, explained for builders.

AeroScope is a Next.js application for live aircraft positions, route enrichment, and lightweight flight intelligence. This page collects the repository essentials in one publishable GitHub Pages reference.

Runtime Next.js App Router
Map stack MapLibre + deck.gl
Data sources OpenSky + AeroDataBox
Pages scope Static docs only

Setup

Run the application locally

Start with the example environment file, install dependencies, then launch the Next.js development server.

Local development 
cp .env.local.example .env.local
npm install
npm run dev

Environment variables

OPENSKY_CLIENT_ID
Optional OpenSky OAuth client id for higher quota.
OPENSKY_CLIENT_SECRET
Optional OpenSky OAuth client secret.
RAPIDAPI_KEY
Optional AeroDataBox key for metadata and route lookup.

Useful checks

  • npm run lint validates the code style.
  • npm run build verifies production bundling.
  • http://localhost:3000 opens the map UI.

How it works

Cache-first live flight intelligence

The app keeps expensive or quota-limited upstream requests behind server routes while the browser stays responsive through local state and manual enrichment actions.

Browser map
/api/stream
OpenSky cache
AeroDataBox on demand
01

Map shell mounts

app/page.tsx renders MapShell, which composes the map, stream subscriber, search, status, and panel.

02

Viewport drives polling

The current map bounding box is stored in Zustand and passed to the stream route for server-side filtering.

03

OpenSky is protected

streamHub keeps a global five-minute snapshot and backs off when upstream rate limits are hit.

04

Metadata stays manual

Aircraft details, route endpoints, and flight search use AeroDataBox only after explicit user action.

API Calls

Internal browser-facing routes

These routes support the application UI. They are useful for debugging and future clients, but they are not versioned as a public API.

GET

/api/stream

Returns cached OpenSky aircraft states, optionally filtered by map bounds.

?lamin=45&lomin=5&lamax=55&lomax=15
GET

/api/aircraft/[icao24]

Loads aircraft registration, model, airline, and image metadata.

/api/aircraft/0200eb
GET

/api/flight-route/[icao24]

Finds a current route by ICAO24, optionally biased by callsign.

?callsign=RAM740X
GET

/api/flight-search

Searches a route by ICAO24-like value, callsign, or flight number.

?q=RAM740X

Deployment

What GitHub Pages publishes here

This repository now includes a Pages workflow that publishes docs-site/. GitHub builds an artifact from those static files and serves it from the repository Pages URL.

Important hosting boundary

GitHub Pages does not run Node.js functions, so it cannot host /api/stream or the AeroDataBox proxy routes. Use Pages for documentation and deploy the actual app to a Node-capable platform such as Vercel, Cloud Run, or Coolify.

Pages source 
.github/workflows/pages.yml
docs-site/index.html
docs-site/styles.css
docs-site/app.js

Maintenance

Keep docs and behavior aligned

Update this page whenever API contracts, cache TTLs, deployment assumptions, or public product behavior changes.

When API routes change

Update the endpoint cards and the deeper notes in docs/integration.md.

When caching changes

Update the architecture flow, operations guide, and README cache summaries.

Before handoff

Run lint and build checks, then manually verify map rendering and route lookup behavior.