cactoandClaude Sonnet 5
6ce487735f
Sets up the microservice home-automation platform skeleton: docker-compose for mosquitto/postgres/clickhouse/redis/rabbitmq, per-service README stubs describing responsibilities, and top-level README with architecture/stack. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
101 lines
3.7 KiB
Markdown
101 lines
3.7 KiB
Markdown
# Home Automation Platform
|
|
|
|
A microservice-based home automation platform, built as a portfolio project
|
|
demonstrating Go (concurrency, message queues, MQTT), PHP/Laravel (API,
|
|
authorization), and polyglot persistence (PostgreSQL, ClickHouse, Redis).
|
|
|
|
**This is not a "growbox project."** A growbox is the first implemented
|
|
**zone** with a first set of **device types** (light, pump, fan, temperature
|
|
sensor). The core system — device management, telemetry, automation rules,
|
|
users, notifications — operates purely on the abstractions *zone*, *device*,
|
|
*device type*, *sensor reading*, *command*, *rule*. Nothing growbox-specific
|
|
is hardcoded in the core: adding a "living room" zone with a "smart plug"
|
|
device type should require zero changes to service code, only new rows in
|
|
`device_types` / `zones` / `devices`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
ESP32 (or emulator)
|
|
│ MQTT
|
|
▼
|
|
ingest-service (Go) ──► ClickHouse (raw telemetry)
|
|
│
|
|
▼ RabbitMQ ("new reading" event)
|
|
rule-engine-service (Go) ──► PostgreSQL (rules, cached)
|
|
│ gRPC (on rule match)
|
|
▼
|
|
device-control-service (Go) ──► MQTT (command) ──► device
|
|
│
|
|
▼
|
|
Redis (device shadow: desired/reported state, status, last_seen)
|
|
|
|
Laravel API (PHP) ──► PostgreSQL / ClickHouse / Redis
|
|
│ gRPC / HTTP
|
|
▼
|
|
device-control-service (manual commands from the UI)
|
|
```
|
|
|
|
## Stack
|
|
|
|
| Concern | Technology |
|
|
|---|---|
|
|
| Device firmware / emulator | Go (`services/esp32-emulator`) |
|
|
| Device ↔ server protocol | MQTT (Mosquitto) |
|
|
| Telemetry / commands / rules backend | Go |
|
|
| Business logic / API / dashboard | PHP (Laravel) |
|
|
| Users, zones, devices, rules | PostgreSQL |
|
|
| Telemetry (time-series) | ClickHouse |
|
|
| Real-time device state | Redis (Device Shadow pattern) |
|
|
| Inter-service async events | RabbitMQ |
|
|
| Inter-service sync calls | gRPC / Protobuf |
|
|
| Metrics (stage 2.5) | Prometheus + Grafana |
|
|
| Containerization | Docker Compose |
|
|
| Web frontend (stage 3) | Vue.js + Inertia.js |
|
|
| Mobile app (stage 3) | Flutter |
|
|
| Notifications | Telegram Bot (MVP) / Firebase Cloud Messaging (later) |
|
|
|
|
## Layout
|
|
|
|
```
|
|
services/
|
|
ingest-service/ Go — MQTT → ClickHouse + RabbitMQ
|
|
device-control-service/ Go — gRPC + MQTT + Redis device shadow
|
|
rule-engine-service/ Go — RabbitMQ consumer + rule evaluation
|
|
health-check-service/ Go — offline detection ticker
|
|
esp32-emulator/ Go — fake device for local dev
|
|
laravel-app/ PHP/Laravel — API, auth, dashboard (stage 2)
|
|
proto/ Shared gRPC contracts (device_control.proto)
|
|
migrations/
|
|
postgres/ users, zones, devices, device_types, automation_rules
|
|
clickhouse/ telemetry table
|
|
configs/mosquitto/ MQTT broker config
|
|
monitoring/ Prometheus + Grafana config (stage 2.5)
|
|
```
|
|
|
|
Each `services/*/README.md` describes that service's responsibility and
|
|
explicit non-responsibilities before any code exists there.
|
|
|
|
## Build stages
|
|
|
|
1. **Go services** — ingest, rule-engine, device-control, ESP32 emulator.
|
|
2. **Laravel** — auth (Sanctum, owner/viewer), CRUD for zones/devices/rules,
|
|
Blade dashboard, manual device control. MVP is considered done here.
|
|
3. *(optional, high value)* **Observability** — Prometheus metrics from the
|
|
Go services, a Grafana dashboard or two.
|
|
4. **Extensions** (no rush) — Telegram notifications, Vue.js/Inertia
|
|
frontend, Flutter app, real ESP32 hardware.
|
|
|
|
## Running locally
|
|
|
|
Infrastructure only for now (app services are added to `docker-compose.yml`
|
|
as they're implemented):
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose up -d
|
|
```
|
|
|
|
This brings up Mosquitto (`1883`), PostgreSQL (`5432`), ClickHouse (`8123`/`9000`),
|
|
Redis (`6379`), and RabbitMQ (`5672`, management UI on `15672`).
|