docs: add alerts subsystem reference

docs/architecture/subsystems/alerts.md

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