fix: added energy-management

energy-management/README.md

@@ -0,0 +1,57 @@
+# 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.