# 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
```bash
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 `#include`s `<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

| Path | Purpose |
|------|---------|
| `server/SHServ/config.php` | DB credentials, device IP scan range, debug mode |
| `server/SHServ/Routes/` | API route definitions (trait-based) |
| `server/SHServ/Controllers/` | Request handler logic |
| `server/SHServ/Models/` | DB query layer |
| `server/console.php` | CLI entry point for server-side scripts |
| `webclient/src/js/sh/SmartHomeApi.js` | JS API client (the contract between frontend and backend) |
| `devices/sh_core_esp8266/src/sh_core.h` | EEPROM layout and all device-side constants |
| `docs/device-spec.md` | Device REST API contract (endpoints on the device itself) |
| `docs/server-api.md` | **Server REST API** — full reference of all implemented endpoints |
| `docs/architecture.md` | Full architecture: firmware contract, events routing, sync map, Fury framework |
| `docs/firmware-dev-guide.md` | How to write firmware for a new device type |
| `docs/control-scripts-guide.md` | How to write automation scripts (Scope classes) |