Architecture Documentation¶

System design, technology decisions, and component interactions for Home Security Intelligence.

Overview¶

Document	Description
Architecture Overview	High-level system design and data flow
Data Model	PostgreSQL schemas and Redis structures
AI Pipeline	Detection to analysis flow
Real-time System	WebSocket and pub/sub architecture
Design Decisions	ADRs - why we made key choices
Resilience	Error handling and graceful degradation
Frontend Hooks	Custom React hook architecture

System Diagram¶

Cameras -> FTP -> FileWatcher -> detection_queue -> YOLO26 -> Detections
                                                          |
Dashboard <- WebSocket <- Events <- Nemotron <- analysis_queue <- BatchAggregator

Technology Stack¶

Layer	Technology	Purpose
Frontend	React + TypeScript	Dashboard UI
Frontend	Tailwind + Tremor	Styling and data visualization
Backend	FastAPI + Python	REST API and WebSocket server
Database	PostgreSQL	Persistent storage
Cache/Queue	Redis	Pub/sub and job queues
Detection	YOLO26	Object detection (30-50ms inference)
Analysis	Nemotron	Risk reasoning via llama.cpp

Component Layers¶

Backend Services¶

Service	Location	Responsibility
FileWatcher	`backend/services/file_watcher.py`	Monitor camera directories
DetectorClient	`backend/services/detector_client.py`	YOLO26 HTTP client
BatchAggregator	`backend/services/batch_aggregator.py`	Group detections into batches
NemotronAnalyzer	`backend/services/nemotron_analyzer.py`	LLM risk analysis
EventBroadcaster	`backend/services/event_broadcaster.py`	WebSocket distribution

Frontend Hooks¶

Hook	Location	Purpose
useWebSocket	`frontend/src/hooks/useWebSocket.ts`	Core WebSocket management
useEventStream	`frontend/src/hooks/useEventStream.ts`	Real-time security events
useSystemStatus	`frontend/src/hooks/useSystemStatus.ts`	System health broadcasts

Deep Dive Documents¶

For detailed implementation specifics, see:

Detection Service - YOLO26 integration
Batching Logic - Time-windowed aggregation
Risk Analysis - Nemotron prompts
Resilience Patterns - Circuit breakers

Back to Developer Hub | Back to Documentation Index