vigilar/docs/architecture/subsystems/events.md

events

Purpose

Central classifier and persistence layer for everything that happens on the MQTT bus. Subscribes to the whole bus, parses topic paths into EventType/Severity/source_id, writes rows into events, evaluates the rule engine against the arm-state FSM, and executes resulting actions (send alert, broadcast system-alert, command all cameras to record).

Key files

• vigilar/events/processor.py — EventProcessor: subscribes via bus.subscribe_all, classifies topics in _classify_event (a big if-chain, no routing table), writes via insert_event, executes rule actions
• vigilar/events/state.py — ArmStateFSM (HOME/AWAY/NIGHT/DISARMED), publishes Topics.SYSTEM_ARM_STATE, persists to arm_state_log
• vigilar/events/rules.py — RuleEngine evaluating TOML-configured rules against topic/payload/arm-state
• vigilar/events/history.py — thin wrapper around get_events/acknowledge_event

MQTT topics

Subscribes: vigilar/# (wildcard via bus.subscribe_all) Publishes:

• vigilar/system/arm_state (from ArmStateFSM)
• vigilar/system/alert (when a rule fires alert_all/push_and_record)
• vigilar/camera/{id}/command/record (per-camera record command for push_and_record/record_all_cameras)

Database tables

• events — canonical event log; every classified message becomes a row
• arm_state_log — arm-state transitions written by the FSM
• pet_sightings — inserted when classification produces PET_DETECTED, PET_ESCAPE, or UNKNOWN_ANIMAL
• wildlife_sightings — inserted for WILDLIFE_PREDATOR/NUISANCE/PASSIVE

Depends on

• Every publisher on the bus (camera, sensors, ups, presence, detection, health, highlights, etc.)
• storage — uses vigilar.storage.queries for all inserts
• alerts — calls send_alert from vigilar.alerts.sender when a rule requests it

Consumed by

• alerts — triggered indirectly via rule actions
• web — reads events table through vigilar.storage.queries for the timeline and SSE stream
• highlights — consumes the events table for reel scoring

Notes

Classification is a hand-written if-chain keyed on the topic path. Camera heartbeat and error topics are intentionally ignored (return None). Person and vehicle YOLO detections ride on camera/{id}/motion/start and currently collapse back to a plain MOTION_START event — a known artefact of the publishing quirk in the camera worker. Arm-state change messages on vigilar/system/* are also deliberately ignored by the classifier to avoid feedback loops.