vigilar/docs/architecture/subsystems/storage.md

storage

Purpose

The persistence layer. Defines every SQLite table, opens the WAL-mode database, exposes hand-written SQLAlchemy Core queries for the rest of the codebase, and provides the AES-256-CTR file encryption used to seal recordings as .vge. It is a library package, not a supervised subsystem process.

Key files

• vigilar/storage/schema.py — SQLAlchemy Core MetaData and 19 Table definitions
• vigilar/storage/db.py — engine creation, WAL pragmas, init_db, get_db_path
• vigilar/storage/queries.py — all insert_*/get_*/update_*/delete_* helpers
• vigilar/storage/encryption.py — AES-256-CTR encrypt_file / decrypt_stream for .vge recordings

MQTT topics

Subscribes: none Publishes: none

Database tables

• cameras — configured camera registry
• sensors — configured sensor registry
• sensor_states — current key/value state per sensor
• events — canonical event log written by the events processor
• recordings — video clip metadata (path, duration, trigger, event_id, starred)
• system_events — operator-facing component log (info/alert/critical)
• arm_state_log — arm-state FSM transitions
• alert_log — one row per alert delivery attempt and outcome
• push_subscriptions — VAPID Web Push subscription endpoints
• pets — known pets (name, species, breed, training count)
• pet_sightings — per-frame pet observations with confidence and crop path
• wildlife_sightings — wildlife observations with species, threat level, weather context
• package_events — package delivery state machine rows (detected/reminded/collected)
• pet_training_images — images staged for pet-ID model retraining
• pet_rules — per-pet rule definitions with cooldown and priority
• face_profiles — known faces, household flag, visit count
• face_embeddings — serialized face vectors linked to a profile
• visits — per-visit records for recognized faces
• timelapse_schedules — per-camera timelapse generation schedules

Depends on

• Filesystem: SQLite database under system.data_dir, AES key at /etc/vigilar/secrets/storage.key

Consumed by

• Every other subsystem. Camera encrypts recordings through it, events/alerts/sensors/ups/pets/highlights/presence/web all import vigilar.storage.queries.

Notes

Encryption is AES-256 in CTR mode (no GCM), so .vge files are confidential but not tamper-evident — there is no authentication tag and a bit-flip in the ciphertext produces a corresponding bit-flip in the plaintext without detection. The 16-byte IV is prepended to each file and the plaintext is unlinked after encryption. The codebase uses SQLAlchemy Core exclusively — there are no mapped ORM classes. The database is opened in WAL mode so the web process can read while the events processor writes.