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
• Web client (webclient/) — JavaScript/SCSS frontend bundled with Gulp/esbuild

Build & Dev Commands

Web Client

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

Compiled via Arduino IDE or PlatformIO. Each device's .ino file #includes <sh_core.h> from devices/sh_core_esp8266/src/. Pre-built 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.

Web Client Structure

• 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