vigilar/docs/architecture/subsystems/alerts.md

alerts

Purpose

Delivers user-facing notifications for events the rule engine has flagged. Provides Web Push (VAPID) delivery to registered browsers and phones, PIN hashing/verification for arm/disarm flows, and a smart-profile matcher that selects recipients based on household state and time-of-day windows. Every alert attempt is logged through vigilar.alerts logger; the main supervisor attaches a dedicated syslog handler to that logger so alerts leave an OS-level audit trail.

Key files

• vigilar/alerts/sender.py — send_alert, build_notification, VAPID Web Push dispatcher; reads push_subscriptions and writes alert_log
• vigilar/alerts/profiles.py — smart alert profile matcher (household state + time windows)
• vigilar/alerts/pin.py — PBKDF2-SHA256 PIN hashing and constant-time verification

MQTT topics

Subscribes: none directly. alerts is not a standalone subsystem process; it is invoked synchronously from the events processor when a rule action fires. Publishes: No MQTT publishers found at time of writing. The events processor publishes vigilar/system/alert on behalf of alert actions.

Database tables

• alert_log — one row per delivery attempt (channel + status + error)
• push_subscriptions — VAPID Web Push subscriptions, read to fan out a notification; stale entries are removed via delete_push_subscription

Depends on

• events — send_alert is called from EventProcessor._execute_action for alert_all / push_and_record
• storage — reads push_subscriptions, writes alert_log

Consumed by

• Phones and browsers — receive Web Push notifications via VAPID
• web — the system blueprint manages push subscription registration and PIN verification

Notes

The vigilar.alerts logger gets a syslog handler installed by the supervisor (vigilar/main.py) so that every alert emission is mirrored into the host's syslog as an out-of-band audit trail, independent of SQLite. PIN verification uses hmac.compare_digest to avoid timing leaks. The smart-profile matcher honours household_state and HH:MM time windows (including windows that wrap past midnight).