# Архитектура 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. Логическая схема

```text
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`