Real-time global aviation dashboard powered by ADS-B transponder data.
A squawk is a 4-digit transponder code assigned by air traffic control to each aircraft. It appears on radar screens to identify flights. The three codes above are reserved worldwide for emergencies and trigger real-time alerts on the dashboard.
A Node.js worker polls the OpenSky Network API every 60 seconds, upserts raw aircraft state into the aircraft table, then computes and persists pre-aggregated metrics into snapshot and agg_* tables. The Next.js BFF reads from SQLite every 5 seconds and pushes updates to the browser over a Server-Sent Events stream. SQLite WAL mode allows the server to read concurrently while the worker is writing.
Flight data comes from the OpenSky Network — a community-driven receiver network that aggregates ADS-B transponder signals from aircraft worldwide. The anonymous endpoint is used (no credentials required), which provides ~400 free requests/day. At 1 request/minute the worker uses ~1,440 requests/day; rate limiting is handled with exponential backoff up to a 10-minute ceiling.
| Layer | Technology |
|---|---|
| Framework | Next.js 15 (App Router) |
| Language | TypeScript 5 |
| Map | deck.gl 9 + MapLibre GL + react-map-gl |
| Charts | Apache ECharts 5 via echarts-for-react |
| Database | SQLite via better-sqlite3 |
| Streaming | Server-Sent Events |
| Worker runner | tsx |
| Concurrency | concurrently |
| Package manager | pnpm |
Prerequisites: Node.js ≥ 20, pnpm
# Install dependencies
pnpm install
# Start the worker (polls OpenSky, writes squawk.db)
pnpm worker
# In a separate terminal — start the Next.js dev server
pnpm devOpen http://localhost:7700.
The worker needs a few seconds to populate the database on first run. The dashboard shows a "connecting…" state until the first snapshot is written.
pnpm build
pnpm start:prodstart:prod uses concurrently to run both processes under a single command with colour-coded output (blue → Next.js, yellow → worker).
Host requirements:
- Persistent disk at
$CWD—squawk.dbis created there at runtime and must survive restarts. - Start command must be
pnpm start:prod, notnext start, so the worker is included. - No environment variables required — OpenSky anonymous endpoint needs no credentials.
The repository ships .github/workflows/deploy.yml which triggers on every push to main and deploys via floo.
Required repository secrets:
| Secret | Description |
|---|---|
FLOO_URL |
Deployment target URL |
FLOO_TOKEN |
Authentication token |
MIT © Christian ECG