- TypeScript 86%
- CSS 13%
- JavaScript <1%
- HTML <1%
Flight Deck #
Flight Deck is a local, map-first flight tracker for monitoring several flights at the same time. Enter one flight number and the application resolves the nearest relevant occurrence, route, schedule, aircraft, and live position without asking for a date or airport.
The backend keeps tracking while the page reloads. Landed flights remain on the watchlist until they are moved to history. All application data and credentials stay on the server.
Flight information comes from independent providers and can be delayed, incomplete, or unavailable. Flight Deck is for personal awareness and must not be used for operational aviation decisions.
Features #
- Track a flight using only its passenger-facing flight number
- Normalize spaces, separators, casing, IATA numbers, and ICAO callsigns
- Track multiple live and scheduled flights concurrently
- Select the closest live or upcoming occurrence automatically
- Arm the next occurrence when the closest result has already landed
- Keep a selected occurrence fixed after it is bound
- Show all available tracked aircraft on a MapLibre map
- Draw course-aware route guides and stored observed trails
- Preserve flight paths while switching map styles and camera modes
- Fit all aircraft, focus one route, or follow the selected aircraft
- Clear a flight selection and fit all aircraft by clicking empty watchlist space
- Show airport-local, device-local, or UTC times
- Show aviation or metric units
- Display schedule, status, airport, aircraft, weather, and event details
- Dismiss any tracked flight to history and restore it later
- Search, inspect, restore, and export dismissed flights from history
- Restore the watchlist and settings from SQLite after a restart
- Stream updates to the browser with Server-Sent Events
- Offer light and dark maps, full screen, optional notifications, and Screen Wake Lock
- Install as a branded Home Screen web app
- Drag the mobile flight details between collapsed, half-height, and expanded views
- Adapt the map, watchlist, and details for desktop, tablet, and mobile screens
Requirements #
- Linux
- Node.js 24 or newer
- npm
- An internet connection for live flight, ADS-B, weather, and map data
- A free AirLabs API key
The project is developed with Node.js 26. The local database uses Node's built-in SQLite support.
No desktop environment is required. The application uses portable Node.js APIs and supports standard x64 and arm64 Linux installations.
Installation #
Install the dependencies:
npm install
Copy the credential template:
cp api.example.json api.json
Replace the placeholder with the AirLabs key:
[
{
"airlabs": "your-api-key"
}
]
Protect the local credential file:
chmod 600 api.json
api.json is ignored by Git. The key is read only by the local backend and is never sent to the browser. The AIRLABS_API_KEY environment variable can be used instead of the JSON file.
Development #
Start the Fastify backend and Vite development server together:
npm run dev
Open:
http://127.0.0.1:5173
Both processes watch for source changes. Stop them with Ctrl+C when finished.
Normal local use #
Build the frontend and backend:
npm run build
Start the compiled local server:
npm run start
Open:
http://127.0.0.1:4174
The compiled server listens on all network interfaces by default. Other devices on the same LAN or Tailscale network can open:
http://your-server-name:4174
You can also use the server's LAN or Tailscale IP address. Router port forwarding is not required for Tailscale.
To restrict the application to the server itself, set VCFTA_HOST=127.0.0.1 before starting it. The application does not include its own authentication, so do not expose port 4174 directly to the public internet.
How tracking works #
When a flight number is added, Flight Deck creates or selects a watch immediately.
- The input is normalized and checked for an existing active watch.
- AirLabs is asked for the closest live, scheduled, or landed occurrence.
- A live or scheduled occurrence is bound to the watch.
- If the closest occurrence has landed, the current schedule horizon is searched for the next flight.
- If the next occurrence is not published yet, the watch remains armed and retries later.
- ADSBDB fills route details when the main response is incomplete.
- ADSB.lol supplies high-frequency positions after an aircraft transponder is known.
- Aviation Weather supplies cached METAR observations for the route airports.
Airborne aircraft positions update about every 15 seconds when provider data is available. If schedule data does not include a transponder, Flight Deck also searches ADSB.lol using the operating callsign and saves the transponder when a matching aircraft appears. Status calls use a slower schedule to conserve the free API allowance. Scheduled and armed watches use progressively slower checks. Provider failures do not delete stored flight state.
Landing can come from the flight provider or from repeated on-ground ADS-B samples near the destination after the flight was airborne. Once landed, frequent position polling stops and the card remains visible.
Local data #
The SQLite database is created at:
.data/flight-deck.sqlite
It stores:
- Flight watches and bound occurrences
- Status and lifecycle events
- Observed position samples
- Dismissed flight history
- Display preferences
The database, WAL files, credentials, build output, and dependencies are ignored by Git.
To start with an empty application, stop the server and move the .data directory somewhere safe. Removing it permanently deletes the local watchlist, trails, and history.
Data providers #
| Provider | Use | Important limitation |
|---|---|---|
| AirLabs | Schedule, status, time, gate, codeshare, and aircraft data | Free allowance and available fields can change |
| ADSB.lol | Live aircraft position and movement | Crowdsourced coverage varies by region |
| ADSBDB | Route and callsign fallback | A route may be missing or outdated |
| Aviation Weather Center | Airport METAR observations | Observations are not available for every airport |
| OpenFreeMap | Basemap style and vector tiles | Requires an internet connection |
Map attribution remains visible in the application. ADS-B data can be stale or absent over oceans and areas with limited receiver coverage. The dotted line follows the live aircraft and its current course when possible, but it remains a visual guide rather than a filed flight plan.
Settings #
Settings are stored locally in SQLite.
- Units: aviation feet and knots, or metric meters and kilometers per hour
- Time display: airport local, this device, or UTC
- Map style: light or dark
- Follow: keep the selected aircraft centered until the map is moved manually
- Flight notifications: requested only after the setting is enabled, then shown for takeoff, landing, and cancellation while Flight Deck is open
- Keep display awake: uses the browser Screen Wake Lock API when supported
Notification and wake lock permission decisions are controlled by the browser. The application continues normally if either feature is unsupported or denied.
Notifications require HTTPS. On iPhone and iPad, use iOS or iPadOS 16.4 or newer, add the HTTPS version of Flight Deck to the Home Screen, and open it from its Home Screen icon before enabling notifications. If an older Home Screen shortcut opens in the browser instead of as a standalone app, remove it and add Flight Deck again.
Flight Deck currently creates notifications from the open web app when it observes a flight state change. It does not register a remote push subscription, so notifications are not delivered after the app has been fully suspended or closed.
Testing #
Run type checking, unit and integration tests, and both production builds:
npm run check
Run only the repeatable test suite:
npm test
Automated tests use local fixtures and in-memory SQLite. They do not call real providers.
Run the opt-in live provider qualification with a known flight number:
npm run qualify:providers -- A3676
This command makes a small number of real requests. It prints a pass, warning, or failure for each capability and never prints the AirLabs key.
Troubleshooting #
The local page does not open #
Make sure the command is still running and use the correct URL for development or compiled use. Another application may already be using port 5173 or 4174.
AirLabs shows as not configured #
Check that api.json matches the documented JSON shape, or set AIRLABS_API_KEY before starting the server. Restart the backend after changing credentials.
A valid flight is waiting for a schedule #
The provider may not publish the next occurrence far in advance. The watch remains armed and checks again without requiring a date.
A flight has no aircraft on the map #
The aircraft assignment or transponder may not be available yet. ADS-B receiver coverage can also be missing. The schedule and route remain visible while position tracking retries.
Airport weather is unavailable #
Some airports have no current METAR. Weather failures do not interrupt flight tracking.
The map is blank #
Confirm that the server and browser can reach OpenFreeMap. Browser privacy tools, DNS filters, or a network outage can block tile requests.
The application shows old state after sleep #
The browser reconnects to the event stream and refreshes its snapshot automatically. Use the flight refresh button if an external provider has not updated yet.
Flight notifications cannot be enabled on iPhone #
Confirm that Flight Deck is being served over HTTPS and was opened from its Home Screen icon. Notifications are not available from an ordinary Safari tab on iPhone. If permission was previously denied, allow notifications for Flight Deck in iOS Settings before trying again.
If the Home Screen still shows the previous generic icon after an update, remove Flight Deck from the Home Screen and add it again so iOS fetches the current app icon.
Privacy and security #
- Fastify listens on all network interfaces by default so the application can be reached from other devices. Set
VCFTA_HOST=127.0.0.1to restrict it to the server. - The AirLabs key stays in the backend process.
- Provider request timeouts prevent stalled connections from hanging the tracker.
- External JSON and incoming API requests are validated.
- Security response headers are added by the local server.
- Provider URLs containing credentials are not logged.
- No account, analytics service, or cloud database is used.
The application still contacts the listed data and map providers, which receive the network information normally associated with an HTTP request.