Smart Monitor

Smart Monitor is a read-only dual-feed mains monitoring application for two Shelly 1PM Gen4 devices upstream of independent UPS feeds. The initial release is permanently constrained to Observe mode: it records telemetry and durable evidence-aware incidents, but does not send real incident mail or perform shutdown actions.

Authentication uses password-first server-side sessions. Per-account TOTP is optional and becomes active only after a generated code confirms enrolment; bootstrap itself creates no MFA material.

Safety invariants

• No relay/output control, schedules, timers, reboot, reset, or firmware operations.
• No subnet discovery or scanning; only the two endpoints in the selected site profile are contacted.
• Device disappearance is evidence of monitor unavailability, not electrically confirmed mains loss.
• Port 8080 is not public and is admitted only from NPM 10.76.50.254 by the Debian host firewall.
• Secrets are provided outside Git. SMTP remains unconfigured until trusted certificate, name mapping, and credential provisioning are approved.

See the architecture for the approved design and deployment for operations.

Development layout

• backend/smart_monitor: API, worker, state engine, adapters, authentication, and persistence.
• frontend: React/TypeScript/Vite WebUI.
• tests: backend, security, database, state, notification, and safety tests.
• alembic: database migrations.
• deploy: example configuration, systemd units, and gated firewall artifact.
• tools: protected local operational material and simulator helpers.

Reproduce the application

python3 -m venv .venv
.venv/bin/pip install -r requirements.lock
.venv/bin/pip install --no-deps -e .
cd frontend
npm ci
npm run build

Apply migrations explicitly as the migration identity, then run smart-monitor seed. Development defaults to the local simulator. The deployed Observe application is available only through https://mon.calhta.com; its DMZ listener is restricted to NPM by nftables. See deployment.md for database roles, protected MFA-key creation, interactive administrator bootstrap, systemd validation, WireGuard, and ingress operations.

Quality gate

.venv/bin/ruff format --check backend tests alembic
.venv/bin/ruff check backend tests alembic
.venv/bin/mypy backend/smart_monitor
.venv/bin/pytest -q
cd frontend
npm run lint
npm test
npm run build
npm audit --audit-level=moderate

The PostgreSQL integration test additionally requires SMART_MONITOR_TEST_DATABASE_URL and must target the dedicated disposable test database. smart-monitor demo-simulator prints the expected healthy, single-unavailable, likely-dual, uncertain, and stable-recovery sequence without network access.