# Peak Power Manager

Keeps your electricity capacity tariff in check by watching live power draw
(from InfluxDB) and shedding/restoring large consumers (via Home Assistant)
whenever the current 15-minute billing block is projected to exceed a target.

## How it works

Belgian-style capacity tariffs bill on the highest 15-minute average power of
the month. Every `CONTROL_LOOP_INTERVAL_MS` (default 10s), the app:

1. Reads recent power samples for the current quarter-hour block from InfluxDB.
2. Projects what that block's final average will be if current draw continues.
3. If the projection exceeds `TARGET_KW`, it sheds the lowest-priority
   configured device (turns a switch off, or lowers a number set-point to its
   floor) via Home Assistant.
4. Once the projection is comfortably back under target, it restores the
   highest-priority shed device.

A minimum dwell time per device (configurable) prevents rapid on/off cycling.
Devices with "manual override" enabled are left alone by the control loop.

## Setup

1. Copy `.env.example` to `.env` and fill in your InfluxDB and Home Assistant
   connection details, the measurement/field that holds live power, and your
   target kW.
2. `docker compose up --build`
3. Open `http://localhost:3000`, go to the **Devices** tab, and add your EV
   charger, heat pump, and any other large consumers with their Home
   Assistant entity IDs, control type (switch or number), and priority
   (lower priority number = shed first).

## Local development

```
npm install
npm run dev:backend   # Fastify API on :3000
npm run dev:frontend  # Vite dev server on :5173, proxies /api to :3000
npm test               # backend unit tests (quarter-hour projection, control decisions)
```

## Architecture

- `backend/src/influx` — queries live power samples from InfluxDB (Flux).
- `backend/src/control/quarterHour.ts` — pure logic computing the running and
  projected average power for the current 15-minute block.
- `backend/src/control/loop.ts` — pure decision logic: which device to shed
  or restore given the projection and device states.
- `backend/src/control/runner.ts` — orchestrates the above against real
  InfluxDB/Home Assistant/SQLite on each tick.
- `backend/src/homeassistant` — Home Assistant REST client and device
  shed/restore abstraction.
- `backend/src/db` — SQLite config store (devices, target, action log, block
  history).
- `frontend/` — React dashboard: live status, device list, 30-day peak
  history chart, recent actions log, and a Devices config page.