CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Project Is

A distributed smart home system with three layers:

• ESP8266/ESP32 firmware (devices/) — IoT devices exposing a REST API
• PHP server (server/) — central backend that manages devices, events, and automation scripts
• Vue web client (webclient-vue/) — Vue 3 + Pinia + Vite frontend using gnexus-ui-kit
• Legacy web client (webclient/) — old vanilla JS frontend (kept as fallback)

Build & Dev Commands

Vue Web Client (webclient-vue/)

cd webclient-vue
npm install       # install dependencies (Vue 3, Pinia, Vite, gnexus-ui-kit, Phosphor icons)
npm run dev       # starts Vite dev server with proxy to PHP backend
npm run build     # production build → dist/
npm test          # runs Vitest unit/component/integration tests
npm run test:coverage  # tests with coverage report

Legacy Web Client (webclient/)

cd webclient
npm install       # install dependencies (esbuild, sass, gulp, browser-sync, etc.)
npm start         # runs gulp: compiles SCSS → dist/css/main.css, bundles JS → dist/js/main.js, watches + live-reloads

PHP Server

No build step. PHP is served directly from server/. Entry point is server/index.php. Configure in server/SHServ/config.php (DB credentials, device IP scan range, debug flag).

IoT Firmware

cd devices
./build.sh   # compiles all targets via arduino-cli, copies release binaries to devices/builds/

Build targets: relay for esp8266:generic and esp32:esp32c3; button for esp8266:d1_mini in x2 and x4 channel variants. Each device's .ino file #includes <sh_core.h> from devices/sh_core_esp8266/src/. Pre-built release binaries live in devices/builds/.

Architecture

Device Provisioning Flow

1. New device boots in setup mode — only /about is public (no auth).
2. Server scans 192.168.x.2–254 (range from config), finds devices via /about.
3. Server calls POST /setup on the device, pushing: auth token, server address, device name/alias, channel schema.
4. Device enters normal mode: all endpoints require Authorization: Bearer <token>.

Device Runtime API

• GET /about — always public, returns device type/firmware info
• GET /status — current channel states (auth required)
• POST /action — control command (auth required)
• Device sends events to server via POST /events/new

Server API (all under /api/v1/)

• /devices/scanning/* — scan network for new devices
• /devices/setup/new-device — register a found device
• /devices/id/{id}/* — info, status, control per device
• /devices/action — execute a device action
• /areas/* — logical groupings of devices
• /scripts/* — automation scripts

Routes are defined as PHP traits in server/SHServ/Routes/ and mixed into the app via server/SHServ/App.php. The underlying framework is a custom MVC called Fury (server/Fury/).

Automation Scripts

PHP classes in server/ControlScripts/Scopes/, extending ControlScripts base class. Each Scope class implements four methods: register_sync_map, register_events_handlers, register_actions_scripts, register_regular_scripts. All Scopes are auto-loaded at startup. See docs/control-scripts-guide.md.

Vue Web Client Structure (webclient-vue/)

• src/app/main.js — Vue app entry (createApp + Pinia + router)
• src/router/routes.js — hash-router routes
• src/api/ — HTTP client: client.js, http.js, mappers.js, modules/{areas,devices,scripts,scanning}.js
• src/stores/ — Pinia stores: areas.js, devices.js, scripts.js, scanning.js, favorites.js
• src/components/ — thin UI adapters (AppShell, AppEmptyState, AppErrorState, AppLoadingState)
• src/features/{areas,devices,scripts}/pages/ — page components using gnexus-ui-kit components
• src/test/mocks/handlers.js — MSW mock handlers for integration tests
• vitest.setup.js — test setup (jsdom, localStorage mock, router stubs, MSW server)

Styling Rules (Vue Client)

• Always use gnexus-ui-kit semantic color classes (.text-success, .text-danger, .bg-primary, .badge-warning, etc.) instead of project-specific CSS custom properties (--color-accent, --color-danger).
• The kit does not expose CSS variables, so prefer composing with its utility classes or currentColor rather than hard-coding hex values.
• This keeps the UI consistent with the design system and avoids drift when the kit's palette evolves.

Legacy Web Client Structure (webclient/)

• webclient/src/js/index.js — app entry point
• webclient/src/js/sh/SmartHomeApi.js — all server API calls
• webclient/src/js/components/ — UI components (hud, modals, toasts, etc.)
• webclient/src/js/routes.js — frontend routing
• webclient/proxy.php — CORS proxy for API calls in dev

sh_core Library (devices/sh_core_esp8266/src/)

Shared Arduino library used by all device firmware:

• sh_core.h — EEPROM memory layout, constants, channel type definitions
• sh_core.cpp — WiFi, OTA, EEPROM helpers
• REST_API.cpp — device HTTP server and endpoint implementations
• WebHandlers.cpp / WebPages.cpp — browser-accessible device config UI

Key Files