wiki/tasks/flightradar24/docs/ARCHITECTURE.md

Архитектура RTL-SDR ingest-контура для FR24 / noisemap

1. Назначение

Этот документ описывает контейнерную архитектуру локального ADS-B контура на RTL-SDR внутри одной VM в PVE.

Цель контура:

• принимать ADS-B поток в real time
• хранить сырьё с retention 3 дня
• автоматически догонять пропуски после сбоя
• хранить данные в PostgreSQL/PostGIS
• отдавать данные в noisemap / карту

2. Ограничения среды

• 1 VM в PVE
• USB RTL-SDR проброшен в VM
• ресурсы VM ограничены:
  • CPU: до 6 vCPU
  • RAM: 10–12 GB
  • SSD: 80–100 GB max
• развёртывание через Docker Compose

3. Логическая схема

RTL-SDR USB
   ↓
capture
   ↓
raw_packets / captures (PostgreSQL)
   ↓
preprocess
   ↓
flights / tracks / track_points / processing_state
   ↓
noise_results
   ↓
noisemap / UI / API

4. Контейнеры

4.1 postgres

Назначение: хранение всех данных проекта.

Содержит:

• captures
• raw_packets
• aircraft
• flights
• track_points
• tracks
• processing_state
• noise_results

Требования:

• PostgreSQL
• PostGIS enabled
• volume для данных
• регулярные backup/restore процедуры

4.2 capture

Назначение: приём ADS-B потока с RTL-SDR.

Функции:

• чтение USB-устройства
• получение live-потока
• запись сырья в PostgreSQL
• фиксация captures
• маркировка границ сессий приёма

Требования:

• лёгкий CPU footprint
• устойчивость к временной потере downstream
• healthcheck
• автоматический рестарт

4.3 preprocess

Назначение: нормализация и догоняющая обработка.

Функции:

• обработка live-потока
• разбор raw_packets
• построение aircraft
• построение flights
• построение tracks и track_points
• обновление processing_state
• recovery с overlap при сбоях

Требования:

• инкрементальная обработка
• дедупликация на границах overlap
• ограничение по памяти
• возможность догонять пропуски автоматически

4.4 api / viewer

Назначение: отдача данных для noisemap.

Функции:

• чтение обработанных данных из PostgreSQL
• отдача треков, точек и шумовых результатов
• фильтрация по периоду и зоне
• API для карты/визуализации

Требования:

• лёгкие запросы
• минимальная логика в рантайме
• кэширование только при реальной необходимости

4.5 monitoring (optional)

Назначение: наблюдение за здоровьем контура.

Функции:

• healthcheck контейнеров
• мониторинг задержки обработки
• мониторинг заполнения диска
• мониторинг статуса RTL-SDR
• алерты при деградации

5. Docker Compose структура

Минимальный compose должен поднимать:

• postgres
• capture
• preprocess
• api

Опционально:

• monitoring

Сетевое правило

• контейнеры общаются внутри одной docker network
• наружу публикуется только api и, если нужно, monitoring
• postgres не публикуется наружу

6. Данные и потоки

6.1 Live flow

1. RTL-SDR → capture
2. capture пишет сырьё в raw_packets
3. preprocess читает сырьё
4. preprocess обновляет flights, tracks, track_points
5. api отдаёт данные на карту

6.2 Recovery flow

1. preprocess обнаруживает отставание
2. ищет недостающий диапазон в raw_packets
3. добирает пропущенные записи
4. обрабатывает с небольшим overlap
5. обновляет processing_state

7. Автозапуск и устойчивость

• контейнеры стартуют после reboot VM
• каждый контейнер имеет healthcheck
• сбой одного контейнера не должен валить всю VM
• capture должен уметь переживать временный разрыв downstream
• preprocess должен уметь догонять запись после восстановления

8. Производительность

С учётом ограничений VM:

• минимизировать число контейнеров и лишних сервисов
• не тащить тяжёлые брокеры очередей без необходимости
• не строить много промежуточных копий данных
• хранить сырьё коротко и чистить автоматически
• тяжёлые вычисления держать инкрементальными

9. Что должно быть детализировано дальше

Следующие документы/итерации должны закрыть:

• схему БД и индексы
• backup/restore
• мониторинг и алерты
• контракт между preprocess и api
• точный формат raw_packets
• стратегию партиционирования

10. Связь с проектом

Этот документ — техническая основа для:

• tasks/flightradar24/PROJECT.md
• tasks/flightradar24/docs/RTL-SDR_TZ.md