# 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`).