alee/vigilar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
965dc3b13d
vigilar/CLAUDE.md
Aaron D. Lee 845a85d618 Initial commit: Vigilar DIY home security system 
Phase 1 (Foundation): project skeleton, TOML config + Pydantic validation,
MQTT bus wrapper, SQLite schema (9 tables), Click CLI, process supervisor.

Phase 2 (Camera): RTSP capture via OpenCV, MOG2 motion detection with
configurable sensitivity/zones, adaptive FPS recording (2fps idle/30fps
motion) via FFmpeg subprocess, HLS live streaming, pre-motion ring buffer.

Phase 3 (Web UI): Flask + Bootstrap 5 dark theme, 6 blueprints, Jinja2
templates (dashboard, kiosk 2x2 grid, events, sensors, recordings, settings),
PWA with service worker + Web Push, full admin settings UI with config
persistence.

Remote Access: WireGuard tunnel configs, nginx reverse proxy with HLS
caching + rate limiting, bandwidth-optimized remote HLS stream (426x240
@ 500kbps), DO droplet setup script, certbot TLS.

29 tests passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-02 23:11:27 -04:00

1.8 KiB
Raw Blame History

Vigilar — Project Conventions

What is this?

DIY offline-first home security system. Python 3.11+, Flask + Bootstrap 5 dark theme, SQLite, MQTT internal bus, FFmpeg recording, HLS streaming.

Stack

  • Web: Flask, Jinja2 templates, Bootstrap 5 (dark), hls.js for camera streams
  • Backend: Python 3.11+, multiprocessing for subsystem isolation, paho-mqtt for internal bus
  • Database: SQLite WAL mode via SQLAlchemy Core (not ORM)
  • Camera: OpenCV (RTSP capture, MOG2 motion detection), FFmpeg subprocess (recording, HLS)
  • Config: TOML (config/vigilar.toml) validated by Pydantic v2
  • CLI: Click

Code Style

  • Ruff for linting, line length 100
  • Type hints on all public functions
  • No docstrings unless logic is non-obvious
  • StrEnum for all string constants (see vigilar/constants.py)
  • SQLAlchemy Core expressions, not ORM — no mapped classes

Architecture

  • Each subsystem (camera, sensors, ups, events, alerts) runs in its own multiprocessing.Process
  • All inter-process communication via local Mosquitto MQTT on 127.0.0.1:1883
  • Web UI is Flask with Blueprints in vigilar/web/blueprints/
  • Templates in vigilar/web/templates/, static assets in vigilar/web/static/

Key Design Decisions

  • Adaptive FPS: 2 FPS idle, 30 FPS on motion, 5-second ring buffer for pre-motion context
  • HLS for multi-camera grid (bandwidth efficient), MJPEG fallback for single-camera low-latency view
  • PWA with Web Push (VAPID) for mobile notifications
  • AES-256 encrypted recordings (.vge files), key in /etc/vigilar/secrets/
  • No cloud dependency, no external service calls in critical path

Commands

  • pip install -e ".[dev]" — install with dev deps
  • vigilar start — launch all services
  • vigilar config validate — check config
  • pytest — run tests
  • ruff check vigilar/ — lint