Architecture

System layers

┌──────────────────────────── Clients ────────────────────────────┐
│  Web app / PWA      Floor-plan screens    Android voice client  │
│  (Vue 3 + Quasar)   (/wui, kiosk)         (Kotlin, wake word)   │
│  Telegram bot       Shared guest links    Any GraphQL caller    │
└───────────────────────────┬─────────────────────────────────────┘
             GraphQL · REST · WebSocket (STOMP)
┌───────────────────────────▼─────────────────────────────────────┐
│                      myHAB backend (Grails 7)                    │
│                                                                  │
│   GraphQL API   ·   Services   ·   Quartz jobs   ·   Event bus   │
│   Spring Security (JWT)   ·   Spring Integration (MQTT)          │
│   Hazelcast (cache, voice sessions)                              │
└───────────────────────────┬─────────────────────────────────────┘
        JDBC          MQTT           HTTPS
┌───────────▼──────┬─────────▼────────┬────────▼──────────────────┐
│   PostgreSQL     │   MQTT broker    │   Vendor clouds           │
│   entities +     │   ESP32, MegaD,  │   FusionSolar, myUplink,  │
│   time series    │   ONVIF bridge   │   Segway, Open-Meteo      │
└──────────────────┴──────────────────┴───────────────────────────┘

Gradle modules

client/android/ is a separate Gradle build, excluded from the root settings.gradle on purpose: the Android Gradle Plugin and the Grails plugin do not coexist in one build, and the two have unrelated release cadences.

Technology stack

Data flow

Sensor readings

Device → MQTT broker → MqttTopicService → PortValueService → PostgreSQL
                              │
                              └──→ WebSocket (STOMP) → every open client

Inbound topics are matched against per-model regular expressions, which is how one subscription (myhab/#) serves ESP boards, meters, inverters, the heat pump, the weather station and the mower without any of them knowing about the others. Patterns are checked in a fixed order and the path segments (/state, /value, /mower/, /emeters/) are chosen so they cannot overlap.

Commands

UI action / scenario / voice / Telegram / shared link
        │  all publish the same event
        ▼
UIMessageService  →  resolves PERIPHERAL | ZONE | PORT to concrete ports
        ▼
PowerService      →  MQTT publish  →  broker  →  device
        ▼                                          │
   event_log row                                   │ device applies + echoes
        ▼                                          ▼
   audit trail                              back through the sensor path

Virtual devices and the broker loopback

Cloud integrations do not bypass the pipeline. A job polls the vendor's REST API and then publishes to the broker; the broker echoes the message back through the same myhab/# subscription, and it is persisted exactly like a reading from a physical sensor.

The weather station, the solar inverter, the smart meter and the mower are all virtual devices treated this way. The benefit is uniformity: one persistence path, one audit path, one WebSocket fan-out, and the MQTT explorer shows cloud data next to hardware data.

Domain model

Zone ──┬── nested Zones
       ├── DevicePeripheral ──┬── DevicePort ── Device ── Rack
       │                      └── Cable ── PatchPanel
       └── Layer

Job ──┬── CronTrigger
      ├── EventTrigger ── EventDefinition ── EventSubscription
      └── Scenario (Groovy DSL)

User ── UserRole ── Role
Configuration    (key/value sidecar on almost any entity)
DashboardScreen ── DashboardScreenBackground
SharedWidget ── SharedWidgetAudit

Seventy-odd GORM domain classes in total, grouped as:

The GraphQL layer

Most of the API is not hand-written. GORM domain classes carrying a static graphql block are auto-registered by a schema factory, which generates queries, list queries with pagination, and CRUD mutations for each.

Hand-written fetchers cover what auto-CRUD cannot express safely:

• Navigation and breadcrumbs.
• Switch, colour and gate operations, which must go through the event path.
• voiceCommand.
• Shared-link administration and its audit read.
• The configuration store, split into an admin view and a narrower UI-safe view.
• Owner-scoped reads such as notification rules.

Realtime

Live state arrives over STOMP on WebSocket, not GraphQL subscriptions. A device state change fans out to every connected client immediately, so two phones and a wall tablet agree without polling.

The public shared-link pages are the exception: they have no authenticated socket, so they re-read state after each action and offer a manual refresh.

Persistence and time series

• Schema is managed by GORM with dbCreate = update — it adds, never removes.
• port_values and event_log are partitioned, with a composite index on (port_id, ts_created DESC) and a BRIN index on ts_created for range pruning.
• An archive schema holds retired partitions.
• Quartz keeps its own qrtz_* tables, so schedules survive restarts.
• Rollup jobs aggregate raw values into hourly, daily and monthly statistics.
• Every timestamp is stored in UTC and rendered per user.

Security model

Caching and sessions

Hazelcast provides distributed caching and holds voice-assistant conversation state (five-minute TTL, capped history). Hibernate's second-level cache is off: it makes external database changes — a restore, a manual fix, the demo's reset — immediately visible to the running application, and at house scale the query volume never justified it.

Observability

• Prometheus metrics, application info and a health endpoint under /actuator, exposed explicitly rather than by default.
• Structured logging via Logback, configurable per package.
• The in-app message inbox surfaces operational events — device offline, integration failures, token expiry — to humans rather than only to logs.
• Job execution history records every scheduled run.
• Grafana can be pointed at the same PostgreSQL for long-range analysis, and embedded back into the UI.

Testing

Backend tests use Spock: unit specs under src/test/groovy and integration specs under src/integration-test/groovy. Static analysis is CodeNarc. The frontend is linted with ESLint and formatted with Prettier.

./gradlew test
./gradlew server-core:test --tests "org.myhab.services.StatisticsServiceSpec"

Build and release

GitHub Actions builds on pushes to master and beta: assemble the combined JAR, build a Docker image on eclipse-temurin:17-jre, and push it to Docker Hub as kirpi4ik/myhab:<version>-<sha>. The demo image (kirpi4ik/myhab-demo) is published from the same commit.