# Обзор

Портал СОНИКС — это Django-монолит, который выступает координатором сети наземных
станций: он знает, какие станции есть, какие спутники наблюдаются, кто и когда что
запланировал, и хранит результаты наблюдений.

## Место портала в системе

Сеть СОНИКС состоит из трёх частей, каждая со своей документацией:

| Компонент | Что делает | Репозиторий |
|---|---|---|
| **Портал** (этот проект) | Учёт станций и спутников, планирование, хранение результатов, API, веб-интерфейс | `soniks-network` |
| **Клиент** | Работает на станции: забирает задания у портала, управляет приёмником и поворотным устройством, отдаёт результаты | `soniks-client` |
| **Флоуграфы** | GNU Radio-флоуграфы, которыми клиент демодулирует принятый сигнал | `soniks-flowgraphs` |

Обмен идёт в одну сторону — клиент сам ходит на портал:

1. Клиент запрашивает `/api/jobs/` при старте и получает список своих будущих наблюдений;
   дальше изменения расписания приходят ему по MQTT (`stations/<id>/jobs`), а без брокера
   он опрашивает тот же эндпоинт раз в минуту.
2. К началу окна наблюдения клиент наводит антенну и запускает флоуграф.
3. По окончании клиент загружает результат обратно: аудио и водопад — в `/api/observations/`,
   демодулированные кадры — в `/api/demoddata/`.
4. Портал оценивает наблюдение (см. [](rating.md)) и публикует его.

## Отношение к SatNOGS

СОНИКС — out-of-tree форк [SatNOGS Network](https://satnogs.org/). От апстрима
унаследованы доменная модель, схема планирования и формат API; расхождения описаны в
[](dev/upstream.md).

Практические следствия:

* Портал умеет подтягивать спутники и передатчики из SatNOGS DB (`DB_API_ENDPOINT`,
  задача `fetch_data`) и разбирать данные из SatNOGS Network (`parse_data_from_satnogs`).
* Часть терминов в коде и API осталась в исходном виде (префикс zip-архивов
  `satnogs-observations`, имена скриптов `satnogs-pre`/`satnogs-post` у клиента).
* Основной репозиторий СОНИКС — на GitLab, merge-request'ы отправляются туда, а не в
  апстрим.

## Из чего состоит портал

Код разложен по четырём Django-приложениям внутри `network/`:

`network.base`
: Ядро — модели, бизнес-логика, HTML-представления, формы, задачи Celery, орбитальная
  механика и интеграции.

`network.api`
: REST API на DRF: сериализаторы, ViewSet'ы, фильтры. Схема OpenAPI генерируется
  `drf-spectacular`.

`network.users`
: Кастомная модель пользователя и профиль.

`network.analytics`
: Суточные метрики по сети и станциям, отдельные модели, запросы и задачи.

Подробнее — в [](dev/architecture.md) и [](dev/models.md).

## Рабочие процессы

* **Наблюдение** — центральная сущность. Жизненный цикл от планирования до оценки описан
  в [](observations.md).
* **Планирование** бывает ручным, автоматическим по расписанию станции или сети, и
  отдельным для новых запусков — см. [](scheduling.md).
* **Орбитальные данные** приходят из нескольких источников с приоритетом и окном
  свежести — см. [](tle.md).

## Технологии

* Backend: Python 3.12, Django 5.2 LTS, Django REST Framework, Celery.
* Хранилища: PostgreSQL 15, Redis 7, S3-совместимое хранилище (Yandex Cloud / AWS),
  InfluxDB (опционально).
* Frontend: Django-шаблоны, SCSS (dart-sass), vanilla JS, Bootstrap 5.3;
  ассеты npm копирует `scripts/copy-assets.mjs`.
* Инфраструктура: Docker, Docker Compose, Nginx, GitLab CI.
* Орбитальная механика: `skyfield`, `sgp4`, `ephem`.
* Интеграции: SatNOGS DB/Network API, Space-Track, CelesTrak, OIDC (Keycloak), Mapbox.

Интерфейс портала на трёх языках (RU/EN/ZH); настоящая документация ведётся на русском.