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 цепочки