Document ADS-B history setup and reporting

docs/FEATURES.md

@@ -38,20 +38,22 @@ Complete feature list for all modules.
 - **Source links** - references to priyom.org for detailed information
 - **Famous stations** - UVB-76 "The Buzzer", Cuban HM01, Israeli E17z
 
-## ADS-B Aircraft Tracking
-
-- **Real-time aircraft tracking** via dump1090 or rtl_adsb
-- **Full-screen dashboard** - dedicated popout with virtual radar scope
-- **Interactive Leaflet map** with OpenStreetMap tiles (dark-themed)
-- **Aircraft trails** - optional flight path history visualization
-- **Range rings** - distance reference circles from observer position
-- **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
-- **Observer location** - manual input or GPS geolocation
-- **Audio alerts** - notifications for military and emergency aircraft
-- **Emergency squawk highlighting** - visual alerts for 7500/7600/7700
-- **Aircraft details popup** - callsign, altitude, speed, heading, squawk, ICAO
+## ADS-B Aircraft Tracking
+
+- **Real-time aircraft tracking** via dump1090 or rtl_adsb
+- **Full-screen dashboard** - dedicated popout with virtual radar scope
+- **Interactive Leaflet map** with OpenStreetMap tiles (dark-themed)
+- **Aircraft trails** - optional flight path history visualization
+- **Range rings** - distance reference circles from observer position
+- **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
+- **Aircraft details popup** - callsign, altitude, speed, heading, squawk, ICAO
 
 <p align="center">
   <img src="/static/images/screenshots/screenshot_radar.png" alt="Screenshot">

docs/USAGE.md

@@ -74,10 +74,42 @@ INTERCEPT automatically detects known trackers:
 
 ### Emergency Squawks
 
-The system highlights aircraft transmitting emergency squawks:
-- **7500** - Hijack
-- **7600** - Radio failure
-- **7700** - General emergency
+The system highlights aircraft transmitting emergency squawks:
+- **7500** - Hijack
+- **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