Перейти до основного вмісту

🏠 Station Overview

A "station" is everything that runs on a single Raspberry Pi: backend (Fastify), frontend (React SPA), Postgres, MQTT broker, plus the native station-agent that manages them. Source lives in the smart-home/ ↗ monorepo.

What a Station Owns​

  • All ESP32 device data (devices, telemetry, events)
  • Local user accounts (synced from Cloud or LAN-only)
  • Automations and kits
  • Firmware artefacts and OTA distribution
  • Wi-Fi network configuration (via station-agent + captive portal)

It works fully offline — Cloud connection is optional and only needed for remote/mobile access.

Topology​

Monorepo Layout​

smart-home/
├── packages/
│   ├── backend/        — Fastify API + WS + MQTT bridge
│   ├── frontend/       — React 18 + Vite SPA
│   └── shared/         — Cross-package TypeScript types + Zod schemas
├── firmware/
│   ├── lib/smart-home-core/   — shared C++ library (Wi-Fi, MQTT, BLE, OTA)
│   ├── esp32-climate/         — temperature + humidity + pressure sensor
│   ├── esp32-pir/             — motion detector
│   ├── esp32-light/           — LED actuator (dimmable)
│   └── esp32-switch-pir/      — wall switch with PIR
├── station-agent/      — Native Node binary on RPi (SEA, self-managed via systemd)
├── deployment/         — Docker Compose, install scripts, nginx config
└── docs/               — Internal design notes (mqtt-protocol, kits, hardware, etc.)

Run Commands​

From the monorepo root:

npm run dev              # Turbo: backend + frontend in watch mode
npm run build            # Turbo: build all packages
npm run lint             # eslint across all packages
npm run check-types      # tsc --noEmit
npm run format           # prettier --write
npm run firmware:build   # build ESP32 firmware (scripts/build-firmware.js)

Release​

All releases via scripts/release.sh ↗ — never edit package.json versions or create tags manually.

TagWhat gets builtWhere it lands
v0.2.77backend + frontend Docker imagesDocker Hub + release.json updated
backend-v0.2.77backend onlyDocker Hub + release.json (frontend untouched)
frontend-v0.2.77frontend onlyDocker Hub + release.json (backend untouched)
firmware-v0.1.5all firmware variantsPublic registry + firmware/manifest.json
firmware-esp32-climate-v0.1.5one firmware variantPublic registry + manifest
agent-v1.0.1station-agent SEA binarysmart-home-updates repo

See Release Flow.

Conventions​

  • Default branch: develop
  • Jira prefix: SHS- (e.g. SHS-42 add device pairing)
  • TS conventions: arrow functions, no classes, enum + Record dispatch — see TypeScript rules ↗

Reference​