# Project Context

This project is a Dockerised SwitchBot temperature dashboard built from an
initial SwitchBot API v1.1 Python proof of concept.

## Current Shape

- `docker-compose.yml` starts three services:
  - `db`: MySQL 8.4 with the `mysql_data` volume.
  - `web`: Flask app served by Gunicorn on port 8000.
  - `collector`: Python polling loop.
- `app/switchbot.py` contains the SwitchBot v1.1 signed request client.
- `app/collector.py` syncs devices from SwitchBot and records sensor readings.
- `app/web.py` serves the dashboard, reports, CSV export, and per-device views.
- `switchbot_poc.py` remains as a low-level API sanity-check script.

## Configuration

Runtime config is provided by `.env`, copied from `.env.example`.

Required values:

```env
SWITCHBOT_TOKEN=...
SWITCHBOT_SECRET=...
FLASK_SECRET_KEY=...
```

Important: do not commit `.env`; it is intentionally ignored.

The default polling interval is:

```env
COLLECT_INTERVAL_SECONDS=900
```

The default timezone is:

```env
APP_TIMEZONE=Europe/London
```

## SwitchBot Notes

The SwitchBot API only exposes devices owned by the account that generated the
token/secret. Devices merely shared with the account do not appear in
`/devices`.

Working discovered devices were:

- `CB11A9610CFB`: `Hub Mini FB`, `Hub Mini2`
- `EE2E01862061`: `Meds Cupboard`, `WoIOSensor`
- `EE2E0446360E`: `Fridge Med`, `WoIOSensor`
- `EE2E05C6434C`: `Main Room`, `WoIOSensor`

`Hub Mini2` is treated as infrastructure. It is stored in the database when
discovered, but hidden from the dashboard/reports and skipped by the collector
for readings.

Current sensor allow-list:

```python
SENSOR_DEVICE_TYPES = {"WoIOSensor"}
```

## Features Implemented

- Responsive dashboard at `/`.
- Sensor cards show latest reading, day low, day high, and battery.
- Hub devices are suppressed from the dashboard.
- Day-so-far graph rendered with local canvas JavaScript, no CDN.
- Clicking a sensor card opens `/devices/<device_id>`.
- Per-device page shows:
  - selected day
  - samples
  - low/high temperature
  - graph for that device/day
  - timestamped readings table
- Reports at `/reports`.
- CSV export at `/reports.csv`.

## Common Commands

Start or restart:

```sh
docker compose up --build -d
```

Follow collector logs:

```sh
docker compose logs -f collector
```

Check row counts:

```sh
docker compose exec -T db mysql -uswitchbot -pswitchbot_password switchbot \
  -e "select count(*) as devices from devices; select count(*) as readings from readings;"
```

Run the original POC:

```sh
python3 switchbot_poc.py
python3 switchbot_poc.py --endpoint /devices/EE2E01862061/status
```

## Verification Performed

- Python syntax checks pass for the app modules.
- Docker build succeeded.
- MySQL became healthy.
- Web app responded with `HTTP 200 OK`.
- Reports and CSV endpoints responded with `HTTP 200 OK`.
- Collector successfully recorded readings for the three `WoIOSensor` devices.
- Browser verification confirmed:
  - dashboard shows only the three sensors
  - Hub Mini is hidden
  - clicking a tile opens the device/day readings page
  - timestamped readings display in local time

## Likely Next Improvements

- Add migrations instead of using `Base.metadata.create_all`.
- Add a manual "collect now" endpoint/button.
- Add CSV export for a single device/day readings table.
- Add alert thresholds for fridge/medicine storage temperatures.
- Add authentication if exposed beyond a trusted local network.