# 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.