ADSB Aircraft Tracking

Aircraft detection and tracking service using AirNav RadarBox API for correlating phenom sightings with known air traffic.

Overview

The ADSB module provides aircraft tracking capabilities by integrating with the AirNav RadarBox On-Demand API. It enables automatic correlation between phenom sighting locations and nearby aircraft, helping the team identify known air traffic in the vicinity of reported phenomena.

The service lives in the /adsb directory of the phenom-backend repository and operates independently from the main Nhost backend, running as a standalone data enrichment pipeline.

Architecture

The ADSB module is composed of two main components.

AirNav CLI (/adsb/airnav/)

A command-line tool that interfaces directly with the AirNav RadarBox On-Demand API. Its responsibilities include:

  • Accepting a geographic area as input (latitude, longitude, radius)
  • Querying the AirNav API for flights within that area
  • Returning structured flight data including aircraft identifiers, positions, altitudes, and headings

Run Phenoms Service (/adsb/run-phenoms/)

An orchestration service that ties phenom data to aircraft queries. Its responsibilities include:

  • Fetching phenom sighting records from Firebase Firestore
  • Extracting location data (coordinates) for each phenom
  • Invoking the AirNav CLI for each sighting location
  • Parsing and writing nearby aircraft data back to the phenom record in Firebase

Key Features

The ADSB ingestion pipeline still reads phenom records from Firebase Firestore. The correlated aircraft data it produces is stored in the Hasura phenom.airnav column and served by the nest-api Worker. Migration of the ingestion side from Firestore to Hasura is pending.

Geographic Flight Queries

The service queries the AirNav RadarBox API using a bounding area around each phenom sighting location. Queries can retrieve both real-time and historical flight data, allowing correlation even for past sightings.

Phenom-to-Aircraft Correlation

For each phenom record, the service identifies aircraft that were in the vicinity at the time of the sighting. Matched aircraft data is stored directly on the phenom record, enriching the dataset for review in the admin dashboard.

Data Store Integration

The ingestion pipeline (adsb/run-phenoms/) reads phenom sighting records from Firebase Firestore (adsb/src/firebaseAdmin.ts) and writes correlated aircraft data back to Firestore. The nest-api Worker then reads the phenom.airnav column from Hasura/Postgres and serves it to the dashboard – the correlated data is stored in Hasura, not read directly from Firestore by the SPA.

The adsb service is the last remaining Firebase consumer in the platform. Migration of its read path from Firestore to Hasura is a known open item.

Admin Dashboard Visualization

Correlated aircraft are rendered in the admin dashboard as interactive rays originating from the phenom sighting location. Each ray is clickable and displays a metadata overlay with flight details such as:

  • Aircraft identifier (ICAO / callsign)
  • Altitude and heading at time of sighting
  • Aircraft type (where available)
  • Distance from phenom location

Data Flow

The following diagram illustrates how a phenom sighting moves through the ADSB correlation pipeline.

sequenceDiagram participant Firebase as Firebase Firestore participant RunPhenoms as Run Phenoms Service participant AirNavCLI as AirNav CLI participant AirNav as AirNav RadarBox API participant Hasura as Hasura / Postgres participant Worker as nest-api Worker participant AdminDash as Admin Dashboard Note over Firebase: Phenom record exists
with location data RunPhenoms->>Firebase: Fetch phenom records (pending migration to Hasura) Firebase-->>RunPhenoms: Return phenoms with coordinates loop For each phenom RunPhenoms->>AirNavCLI: Query area (lat, lon, radius) AirNavCLI->>AirNav: GET flights by geographic area AirNav-->>AirNavCLI: Return nearby flight data AirNavCLI-->>RunPhenoms: Structured aircraft list RunPhenoms->>Hasura: Write aircraft data to phenom.airnav column end AdminDash->>Worker: GET /api/events (Bearer JWT) Worker->>Hasura: GraphQL query (phenom.airnav included) Hasura-->>Worker: Phenom rows with airnav data Worker-->>AdminDash: Normalised events response AdminDash->>AdminDash: Render interactive aircraft rays

Steps Summary

  1. A phenom sighting exists in Firestore with a geographic location.
  2. The Run Phenoms service fetches phenom locations from Firebase Firestore (this read path is pending migration to Hasura).
  3. The AirNav CLI queries the RadarBox API for flights near each location.
  4. The service writes correlated aircraft data to the phenom.airnav column in Hasura/Postgres.
  5. The admin dashboard fetches events via the nest-api Worker, which includes the airnav column from Hasura, and renders aircraft as interactive rays with metadata overlays.

Repository Layout

phenom-backend/
└── adsb/
    ├── airnav/          # AirNav RadarBox API CLI
    │   ├── main.go      # Entry point and CLI argument parsing
    │   ├── client.go    # HTTP client for AirNav API
    │   └── models.go    # Flight data structs
    └── run-phenoms/     # Phenom-to-aircraft correlation service
        ├── main.go      # Orchestration entry point
        ├── firebase.go  # Firebase Firestore read/write
        └── correlate.go # Matching logic and data mapping

Last modified June 22, 2026: docs(#383): GlitchTip runbook + register in nest-ops asset index (#384) (fbe78ef)