MQTT Project

Интеграционная платформа для приема MQTT-пакетов, передачи их через Kafka, интерпретации и хранения.

Devices -> Mosquitto -> bus -> Kafka -> core -> ClickHouse
                                      |
                                      -> PostgreSQL: users, devices, app data

Состав

• core - Laravel API и обработчики Kafka-пакетов.
• bus - MQTT consumer, который принимает пакеты и передает их в Kafka.
• frontend - Vue 3 + Bootstrap 5 frontend.
• laradock - Docker-инфраструктура проекта.

Требования

• Docker и Docker Compose plugin.
• Node.js/npm для локальной frontend-разработки вне контейнера.
• Доступ на запись в /etc/hosts для локальных доменов.

Быстрый старт

Добавьте локальные домены в /etc/hosts:

127.0.0.1 api.mqtt.local
127.0.0.1 mqtt.local

Из корня проекта запустите инфраструктуру и установите зависимости:

make build
make up
make core-install
make bus-install
make frontend-install
make frontend-build
make core-migrate
make core-seed
make core-clickhouse
make check

После запуска доступны:

Сервис	URL
API	http://api.mqtt.local
Horizon	http://api.mqtt.local/horizon
Telescope	http://api.mqtt.local/telescope
Mercure	http://localhost:1337/.well-known/mercure
Grafana	http://localhost:3002, admin / admin
Prometheus	http://localhost:9090
Frontend	http://mqtt.local
Bus health	http://localhost с заголовком Host: bus.localhost

Health-check API:

curl http://api.mqtt.local/health
curl http://api.mqtt.local/ready

Frontend собирается в frontend/dist и обслуживается nginx из laradock/nginx/sites/00-frontend.conf.

Демо-администратор после make core-seed: admin@example.com / password123. После входа frontend показывает admin-таблицы пользователей и устройств.

Локальная разработка frontend

Можно работать через make-команды:

make frontend-install
make frontend-build
make frontend-health

Или напрямую из каталога frontend:

cd frontend
npm install
npm run dev
npm run build

Для production-проверки через Laradock используйте make frontend-build, затем откройте http://mqtt.local.

Worker-процессы

Worker-процессы запускаются отдельно в интерактивном режиме:

make bus-consume
make core-consume
make core-horizon

Архитектурные правила

Правила DDD, CQRS и Hexagonal Clean Architecture вынесены в RFC: сохранение архитектуры. Изменения, которые нарушают эти инварианты, оформляются отдельным RFC до реализации.

Проверки и CI

Локальные проверки:

make check
make core-test
cd bus && composer test

В GitLab CI и GitHub Actions настроены одинаковые проверки: Composer validate, PHP syntax checks, PHPStan/Psalm для core и bus, Laravel tests для core и unit-тесты bus. Core test jobs устанавливают PHP extensions pcntl, redis, pdo_pgsql, pdo_sqlite и rdkafka; Telescope отключается на key:generate и тестах через TELESCOPE_ENABLED=false.

Полезные команды

make status
make logs service=nginx
make shell
make down
make restart

Полный список команд описан в docs/makefile.md.

Документация

Полная документация хранится в репозитории и синхронизируется в wiki. Source of truth остается в Git: изменения документации проходят через обычный review вместе с кодом.

• Архитектура
• Инфраструктура
• RFC: сохранение архитектуры
• Makefile-команды
• Bus
• Core
• Frontend
• Проверка и статический анализ
• Замечания
• Отчеты о проделанной работе
• Скрипты синхронизации

Диаграмма архитектуры хранится в PlantUML-исходнике docs/architecture.puml; PNG для просмотра лежит в docs/assets/architecture.png.

Wiki:

• GitHub Wiki: https://github.com/robotateme/mqtt-project/wiki
• GitLab Wiki: https://gitlab.com/robotateme/mqtt-project/-/wikis/home