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

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.

Firebase Integration

The service reads phenom sighting data from Firebase Firestore and writes correlated aircraft records back to the same data store. This keeps aircraft correlation data co-located with the original phenom records without requiring schema changes to the Hasura/PostgreSQL layer.

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 AdminDash as Admin Dashboard Note over Firebase: Phenom record created
with location data RunPhenoms->>Firebase: Fetch phenom records 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->>Firebase: Write aircraft data to phenom record end AdminDash->>Firebase: Load phenom with aircraft data Firebase-->>AdminDash: Phenom + correlated aircraft AdminDash->>AdminDash: Render interactive aircraft rays

Steps Summary

  1. A phenom sighting is created with a geographic location.
  2. The Run Phenoms service fetches the phenom location from Firebase.
  3. The AirNav CLI queries the RadarBox API for flights near that location.
  4. The service writes the returned aircraft data back to the phenom record in Firebase.
  5. The admin dashboard reads the enriched phenom record 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