wiki/tasks/flightradar24/docs/INGEST_API_CONTRACT.md

Ingest ↔ API contract

Principle

The contract between ingest and API is the PostgreSQL schema. Ingest writes rows; API reads the same rows. No file exchange is required for the core data path.

API read model

The API reads these tables:

• fr24.captures — capture sessions and source metadata
• fr24.raw_packets — raw base64 packets with radio metadata
• fr24.aircraft — aircraft identity and enrichment
• fr24.flights — flight sessions and state
• fr24.tracks — track aggregates
• fr24.track_points — ordered track geometry points
• fr24.processing_state — recovery cursors and pipeline state
• fr24.noise_results — computed noise polygons and summaries

Ingest write model

• capture writes captures and raw_packets
• preprocess writes aircraft, flights, tracks, track_points, processing_state, noise_results
• monitoring does not own core data; it reports status and alerts

Planned endpoints

• GET /health
• GET /captures
• GET /raw-packets with pagination and time filters
• GET /aircraft
• GET /flights
• GET /tracks/{track_id}
• GET /track-points?track_id=...
• GET /noise-results
• GET /dashboard/status
• GET /viewer/config

Query expectations

• API should prefer indexed filters by time, flight, aircraft, and partition date.
• API should not reconstruct track geometry from raw packets at request time.
• API should read prebuilt aggregates from tracks and track_points.

Retention expectations

• raw_packets keep 3 days by default.
• Cleanup is partition-based by date.
• Aggregated tables may retain longer, depending on UI needs.