From c4d119310afa98182535904d9f77c14eeb831cd8 Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Sun, 5 Apr 2026 09:48:54 -0400 Subject: [PATCH] docs: add health subsystem reference --- docs/architecture/subsystems/health.md | 39 ++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/architecture/subsystems/health.md diff --git a/docs/architecture/subsystems/health.md b/docs/architecture/subsystems/health.md new file mode 100644 index 0000000..755ca03 --- /dev/null +++ b/docs/architecture/subsystems/health.md @@ -0,0 +1,39 @@ +# health + +## Purpose + +Self-monitoring and housekeeping. Periodically checks disk usage and MQTT reachability, publishes an aggregated system-health snapshot, auto-prunes old recordings when the disk gets full, builds a daily "what happened today" digest, and drives the scheduled firing of highlight-reel and timelapse jobs. + +## Key files + +- `vigilar/health/monitor.py` — `HealthMonitor` subsystem loop: disk check every 5 min, MQTT port check every 30 s, status publish every 10 s, daily reel trigger, per-minute timelapse schedule check +- `vigilar/health/pruner.py` — `auto_prune` / `find_prunable_recordings`; deletes oldest unstarred recordings (and their thumbnails) until usage is back under target +- `vigilar/health/digest.py` — `build_digest`: counts person/vehicle events, pet and wildlife sightings, and recording totals over a time window for notification digests +- `vigilar/health/__init__.py` + +## MQTT topics + +**Subscribes:** none +**Publishes:** +- `vigilar/system/health` — rolled-up health status with per-check breakdown + +## Database tables + +- `recordings` — read in pruner (`starred = 0`, oldest first) and deleted row-by-row once the file is unlinked +- `events`, `pet_sightings`, `wildlife_sightings`, `recordings` — read in `digest.py` +- `timelapse_schedules` — read indirectly via `vigilar.highlights.timelapse.check_schedules` + +## Depends on + +- `storage` — all DB access +- `highlights` — calls `generate_daily_reel` and `check_schedules` on schedule +- Filesystem — `shutil.disk_usage` on `system.data_dir` + +## Consumed by + +- `web` — surfaces `vigilar/system/health` and the digest output in the system blueprint +- `events` — ingests `vigilar/system/health` off the bus (subscribes to everything) + +## Notes + +The pruner is keyed on percentages, not gigabytes: it checks `config.health.disk_warn_pct` / `disk_critical_pct` for alerting and prunes toward `config.health.auto_prune_target_pct`. It never deletes a recording whose `starred` flag is set, and it unlinks the thumbnail alongside the video. The monitor owns the scheduling clock for both `generate_daily_reel` (fires when wall-clock matches `highlights.generate_time`) and timelapse generation (polls `check_schedules` every 60 s), so neither `highlights/` nor its cron is wired directly into the supervisor.