From 561506ed9192eb9fb65fe9967bf339ccc1634369 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Mon, 11 May 2026 07:28:42 +0400
Subject: [PATCH] =?UTF-8?q?README:=20=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D0=BD?=
 =?UTF-8?q?=D0=B8=D0=B5=20=D1=81=D0=B5=D1=80=D0=B2=D0=B8=D1=81=D0=B0,=20?=
 =?UTF-8?q?=D0=B0=D1=80=D1=85=D0=B8=D1=82=D0=B5=D0=BA=D1=82=D1=83=D1=80?=
 =?UTF-8?q?=D0=B0,=20=D0=BA=D0=BE=D0=BC=D0=B0=D0=BD=D0=B4=D1=8B,=20=D1=8D?=
 =?UTF-8?q?=D0=BD=D0=B4=D0=BF=D0=BE=D0=B8=D0=BD=D1=82=D1=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c4514ff
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# IoT Managed Service
+
+## Назначение
+
+IoT Managed Service — это облачный сервис для управления IoT-устройствами, сбора и хранения телеметрии, а также интеграции с внешними системами через MQTT, Kafka и REST API.
+
+Сервис автоматизирует регистрацию устройств, выдачу credentials, сбор телеметрии и предоставляет REST-интерфейс для управления и мониторинга.
+
+---
+
+## Архитектура
+
+- **IoT Device** — физическое устройство, подключающееся по MQTT
+- **EMQX** — брокер MQTT, делегирует auth/ACL в iot-operator
+- **iot-mqtt-bridge** — подписка на все топики, проксирует в Kafka
+- **Kafka** — очередь событий телеметрии
+- **iot-kafka-consumer** — сохраняет телеметрию в per-tenant Postgres
+- **IoT Postgres** — база данных для хранения телеметрии
+- **REST API** — управление устройствами, получение телеметрии
+
+---
+
+## Основные компоненты
+
+| Компонент         | Назначение                        |
+|-------------------|-----------------------------------|
+| iot-operator      | REST API, контроллер CRD          |
+| iot-mqtt-bridge   | MQTT → Kafka                      |
+| iot-kafka-consumer| Kafka → Postgres                  |
+| iot-postgres      | Хранение телеметрии               |
+| EMQX              | MQTT брокер                       |
+
+---
+
+## Основные команды и эндпоинты
+
+### Публичные
+- `GET /console` — IoT Console (SPA)
+- `GET /iot-admin` — страница администратора
+
+### JWT (namespace)
+- `POST /v1/namespaces/{ns}/iot/devices` — создать устройство
+- `GET /v1/namespaces/{ns}/iot/devices` — список устройств
+- `GET /v1/namespaces/{ns}/iot/devices/{name}` — получить устройство + пароль
+- `DELETE /v1/namespaces/{ns}/iot/devices/{name}` — удалить устройство
+- `PATCH /v1/namespaces/{ns}/iot/devices/{name}` — обновить (enabled)
+- `GET /v1/namespaces/{ns}/iot/telemetry` — получить телеметрию
+
+### Внутренние (без JWT)
+- `POST /internal/mqtt/auth` — MQTT auth для EMQX
+- `POST /internal/mqtt/acl` — MQTT ACL для EMQX
+
+### Админ
+- `GET /iot-admin/stats` — статистика (PG, Kafka, pods)
+
+---
+
+## Быстрый старт
+
+1. Развернуть EMQX, iot-mqtt-bridge, event-dispatcher, iot-kafka-consumer, iot-postgres (см. deployments/k8s/)
+2. Зарегистрировать устройство через REST API или CRD
+3. Подключить устройство к MQTT (логин/пароль выдаются автоматически)
+4. Телеметрия автоматически попадёт в Postgres и доступна через REST API
+
+---
+
+## Документация
+- doc/architecture/overview.md — архитектура
+- doc/api/endpoints.md — список эндпоинтов
+- doc/deployment.md — деплой и инженерные детали
+- examples/README.md — пример E2E цепочки