# Общая архитектура

Платформа ARTEX построена по схеме «звезда»: в центре находится **ХАБ платформы**, к которому независимо подключаются роботы, операторы и модели ИИ. Никто из участников не общается напрямую — все потоки проходят через ХАБ, который коммутирует их, кэширует актуальное состояние и сохраняет данные.

## Общая схема

```
                          ┌──────────────────────────────────────────────┐
  Зарегистрированные      │               ХАБ ПЛАТФОРМЫ                  │     Зарегистрированные
  роботы                  │            (Go / C++, Docker + K8s)          │     операторы
                          │                                              │
 ┌──────────┐  видео      │  ┌───────────┐   ┌─────────────────────────┐ │  WebSocket  ┌────────────┐
 │ Робот 1  │────────────▶│  │ Коммутатор│◀─▶│ Общая память            │ │◀───────────▶│ Оператор 1 │
 │ artex-   │  телеметрия │  │ потоков   │   │ (неблокирующий кэш)     │ │  WebRTC     │ (Web UI)   │
 │ robot SDK│────────────▶│  └───────────┘   └─────────────────────────┘ │────────────▶└────────────┘
 │          │◀────────────│         │                   │                │                  ...
 └──────────┘  команды    │         ▼                   ▼                │             ┌────────────┐
      ...                 │  ┌─────────────┐   ┌─────────────────────┐   │             │ Оператор N │
 ┌──────────┐             │  │ Управление  │   │ Хранилище: S3,      │   │             └────────────┘
 │ Робот N  │◀───────────▶│  │ доступом    │   │ Time Series DB,     │   │
 └──────────┘             │  │ JWT / RBAC  │   │ PostgreSQL, Redis   │   │
                          │  └─────────────┘   └─────────────────────┘   │
                          └───────────────────────▲──────────────────────┘
                                                  │ Socket / WebRTC
                                                  ▼
                          ┌──────────────────────────────────────────────┐
                          │   Распределённая вычислительная среда        │
                          │   (Docker, K8s, GPU)                         │
                          │   Модели ИИ оператора 1 … оператора N        │
                          │   YOLO · Assist AI · RL Agent · Custom       │
                          └──────────────────────────────────────────────┘
```

## Три потока данных

Между участниками передаются три типа данных. Каждый поток идёт по своему каналу, чтобы тяжёлое видео не задерживало команды управления.

| № | Поток | Направление | Содержание |
|---|---|---|---|
| 1 | **Телеметрия, признаки** | Робот → ХАБ → оператор и модели ИИ | Скорость, координаты, данные гироскопов и акселерометров, заряд АКБ, состояние дополнительных агрегатов, признаки (векторы), выделенные бортовыми моделями ИИ |
| 2 | **Управление** | Оператор / модель ИИ → ХАБ → робот | Управление движением, поворотом камеры, дополнительными аксессуарами. Основной источник — модель ИИ; оператор управляет при обучении или «подстраховке» модели |
| 3 | **Видео** | Робот → ХАБ → оператор и модели ИИ | Видео с камер, а также данные радаров, лидаров и т.п., преобразованные в видео. Оператору — для управления от первого лица и контроля работы ИИ; моделям — для анализа |

## Компоненты платформы

| Компонент | Технологии | Ответственность |
|---|---|---|
| **Робот** | Python, SDK `artex-robot`, OpenCV | Съёмка видео и передача на сервер; сбор и передача телеметрии; работа бортовых моделей ИИ (обработка видео и данных датчиков); получение и применение команд управления |
| **Платформа (ХАБ)** | Go, C++ | Идентификация роботов; приём видео и телеметрии, загрузка в кэш и хранилище; неблокирующий кэш с методами `push` и `get`; коммутация роботов, операторов и моделей; подключение операторов и моделей к видео и данным |
| **Оператор (Web-приложение)** | React, WebSocket, WebRTC | Приём видео и телеметрии от робота; управление роботом и передача управления на платформу; мониторинг работы моделей ИИ, их входных и выходных данных и логов; адаптивный интерфейс для ноутбука и телефона |
| **Вычислительная среда** | Docker, Kubernetes, GPU | Обработка видео (YOLO); обработка временных рядов, RL; формирование команд управления |
| **Хранилище** | S3 / MinIO, Time Series DB, PostgreSQL, Redis | Сохранение видео, телеметрии, команд и логов; развёртывание, подключение и тестирование хранилища |
| **Управление платформой (WEB-портал)** | Web | Мониторинг подключённых роботов и операторов; ограничение «видимости» роботов для операторов; настройка сохранения данных |

## Типы подключаемых устройств

| Класс устройств | Типичные контроллеры | Способ подключения |
|---|---|---|
| RC-танки, машинки | ESP32 / STM32 + бортовой компьютер (Raspberry Pi 4) | SDK `artex-robot` |
| Наземные роботы | ROS2 / собственное ПО | SDK `artex-robot` (узел-мост) |
| Дроны (БПЛА) | PX4 / ArduPilot + компаньон-компьютер | SDK `artex-robot` |
| IoT-датчики | MQTT / GPIO | MQTT-брокер (планируется) |
| Светодиодные устройства (LED, RGB-лента) | Любой Python-контроллер | SDK `artex-robot` (тип `LED`) |
| Виртуальные роботы | Unity / Gazebo | SDK `artex-robot` — тот же протокол, что и у реальных |

## Принципы архитектуры

1. **Всё через ХАБ.** Роботы, операторы и модели не знают адресов друг друга — это упрощает подключение, контроль доступа и запись данных.
2. **Неблокирующая общая память.** ХАБ хранит только *актуальный* кадр и *актуальный* вектор телеметрии (с отметкой времени). Медленный потребитель не тормозит быстрого: каждый читает последнее значение методом `get`.
3. **Модель и человек равноправны.** Команды от оператора и от модели ИИ имеют одинаковый формат; различается только автор и приоритет.
4. **Модульность.** Серверная логика собирается из модулей в визуальном редакторе с горячей перезагрузкой (hot reload). Каждый сервис — отдельный Docker-контейнер.
5. **Всё записывается.** Видео, телеметрия и команды (включая автора команды) сохраняются для анализа и обучения.

Подробнее: [Протоколы и потоки данных](https://docs.mephi-ai.ru/books/server-upravleniia-robotami/page/protokoly-i-potoki-dannyx), [Серверные модули](https://docs.mephi-ai.ru/books/server-upravleniia-robotami/page/servernye-moduli), [Хранение данных](https://docs.mephi-ai.ru/books/server-upravleniia-robotami/page/xranenie-dannyx).