docs: add camera subsystem reference

docs/architecture/subsystems/camera.md

@@ -0,0 +1,44 @@
+# camera
+
+## Purpose
+
+Owns all per-camera capture, motion detection, recording, and live streaming. One worker process per configured camera pulls RTSP frames with OpenCV, runs MOG2 background-subtraction motion detection plus optional YOLO object detection, writes H.264 segments via FFmpeg, and exposes HLS for the web grid.
+
+## Key files
+
+- `vigilar/camera/manager.py` — `CameraManager`, spawns and supervises one `multiprocessing.Process` per camera; polled by main supervisor via `check_and_restart()`
+- `vigilar/camera/worker.py` — per-camera capture loop: RTSP read, ring buffer push, motion detect, adaptive-FPS record, YOLO classification, MQTT publish
+- `vigilar/camera/motion.py` — MOG2-based `MotionDetector`
+- `vigilar/camera/recorder.py` — FFmpeg-subprocess recorder with idle and motion modes; calls `vigilar.storage.encryption.encrypt_file` to produce `.vge` output
+- `vigilar/camera/ring_buffer.py` — 5-second pre-motion frame buffer
+- `vigilar/camera/hls.py` — HLS segment writer for the web grid view
+
+## MQTT topics
+
+**Subscribes:** `vigilar/camera/{id}/config` (runtime threshold updates)
+**Publishes:**
+- `vigilar/camera/{id}/motion/start` (MOG2 trigger, and YOLO person/vehicle detections)
+- `vigilar/camera/{id}/motion/end`
+- `vigilar/camera/{id}/heartbeat`
+- `vigilar/camera/{id}/error`
+- `vigilar/camera/{id}/pet/detected`
+- `vigilar/camera/{id}/wildlife/detected`
+- `vigilar/pets/{pet_name}/location` (when a known pet is identified)
+
+## Database tables
+
+The camera subsystem does not write to SQLite directly; recording metadata and events are persisted by the `events` subsystem after consuming motion topics. Encrypted clips are written to disk by `recorder.py`.
+
+## Depends on
+
+- `storage` — uses `vigilar.storage.encryption.encrypt_file` to seal recordings as `.vge`
+- `detection` — optional YOLO detector, pet classifier, and wildlife threat classifier are loaded into the worker process
+
+## Consumed by
+
+- `events` — subscribes to the whole bus and classifies motion/heartbeat/error topics into rows in `events` and `recordings`
+- `web` — reads HLS segments for the camera grid and decrypts recordings for playback
+
+## Notes
+
+`CameraManager` is the one subsystem NOT wrapped in `SubsystemProcess`; it owns its own child processes and is polled directly from the main supervisor loop. Adaptive FPS runs at 2 FPS idle and 30 FPS while motion is active, with a 5-second ring buffer flushed into the front of each motion clip for pre-event context. YOLO person/vehicle detections are published as extra `motion/start` messages with an additional `detection` field rather than on dedicated topics.