Document ADS-B history setup and reporting

README.md

@@ -33,6 +33,7 @@ Support the developer of this open-source project
 - **ACARS Messaging** - Aircraft datalink messages via acarsdec
 - **Listening Post** - Frequency scanner with audio monitoring
 - **Satellite Tracking** - Pass prediction using TLE data
+- **ADS-B History** - Persistent aircraft history with reporting dashboard (Postgres optional)
 - **WiFi Scanning** - Monitor mode reconnaissance via aircrack-ng
 - **Bluetooth Scanning** - Device discovery and tracker detection
 - **Spy Stations** - Number stations and diplomatic HF network database
@@ -61,6 +62,29 @@ docker compose up -d
 
 > **Note:** Docker requires privileged mode for USB SDR access. See `docker-compose.yml` for configuration options.
 
+### ADS-B History (Optional, Postgres)
+
+The ADS-B history dashboard persists aircraft messages and snapshots to Postgres.
+
+1. Enable history and DB connection:
+
+```bash
+export INTERCEPT_ADSB_HISTORY_ENABLED=true
+export INTERCEPT_ADSB_DB_HOST=adsb_db
+export INTERCEPT_ADSB_DB_PORT=5432
+export INTERCEPT_ADSB_DB_NAME=intercept_adsb
+export INTERCEPT_ADSB_DB_USER=intercept
+export INTERCEPT_ADSB_DB_PASSWORD=intercept
+```
+
+2. Start the services (includes Postgres in `docker-compose.yml`):
+
+```bash
+docker compose up -d
+```
+
+3. Open **/adsb/history** for the reporting dashboard and headless start/stop controls.
+
 ### Local Fixes Branch (Optional)
 
 If you keep local changes (e.g., custom health checks), use a separate branch and rebase it after updates:

docs/FEATURES.md

@@ -48,6 +48,8 @@ Complete feature list for all modules.
 - **Aircraft filtering** - show all, military only, civil only, or emergency only
 - **Marker clustering** - group nearby aircraft at lower zoom levels
 - **Reception statistics** - max range, message rate, busiest hour, total seen
+- **Persistent ADS-B history** - optional Postgres-backed message and snapshot storage
+- **History reporting dashboard** - session controls, aircraft timelines, and detail modal
 - **Observer location** - manual input or GPS geolocation
 - **Audio alerts** - notifications for military and emergency aircraft
 - **Emergency squawk highlighting** - visual alerts for 7500/7600/7700

docs/USAGE.md

@@ -79,6 +79,38 @@ The system highlights aircraft transmitting emergency squawks:
 - **7600** - Radio failure
 - **7700** - General emergency
 
+## ADS-B History (Optional)
+
+The history dashboard persists aircraft messages and per-aircraft snapshots to Postgres for long-running tracking and reporting.
+
+### Enable History
+
+Set the following environment variables (Docker recommended):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `INTERCEPT_ADSB_HISTORY_ENABLED` | `false` | Enables history storage and reporting |
+| `INTERCEPT_ADSB_DB_HOST` | `localhost` | Postgres host (use `adsb_db` in Docker) |
+| `INTERCEPT_ADSB_DB_PORT` | `5432` | Postgres port |
+| `INTERCEPT_ADSB_DB_NAME` | `intercept_adsb` | Database name |
+| `INTERCEPT_ADSB_DB_USER` | `intercept` | Database user |
+| `INTERCEPT_ADSB_DB_PASSWORD` | `intercept` | Database password |
+
+### Docker Setup
+
+`docker-compose.yml` includes an `adsb_db` service and a persistent volume for history storage:
+
+```bash
+docker compose up -d
+```
+
+### Using the History Dashboard
+
+1. Open **/adsb/history**
+2. Use **Start Tracking** to run ADS-B in headless mode
+3. View aircraft history and timelines
+4. Stop tracking when desired (session history is recorded)
+
 ## Satellite Mode
 
 1. **Set Location** - Choose location source: