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

| 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` | Legacy JS API client |
| `webclient-vue/src/api/client.js` | Vue API client wrapper |
| `webclient-vue/src/app/main.js` | Vue app entry point |
| `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) |
| `webclient-vue/docs/migration-plan.md` | Vue client migration plan (Phases 1–6) |
| `webclient-vue/docs/smoke-checklist.md` | UI smoke checklist for releases |