Reference Hub¶

Authoritative reference documentation for the Home Security Intelligence system. Lookup-style information for APIs, configuration, and troubleshooting.

Target Audiences: Developers, Operators, Support, All Users

Section	What You'll Find
Environment Variables	All configuration options with defaults
Service Ports	Port assignments for all services
Glossary	Definitions of key terms
Troubleshooting	Symptom-based problem solving
API Reference	REST and WebSocket API documentation
Risk Levels	Risk score ranges and severity definitions

Service Ports¶

Service	Port	Protocol	Description
Frontend HTTP	5173	HTTP	React dashboard via nginx (configurable: `FRONTEND_PORT`)
Frontend HTTPS	8443	HTTPS	React dashboard via nginx (configurable: `FRONTEND_HTTPS_PORT`)
Backend API	8000	HTTP/WS	FastAPI REST + WebSocket
YOLO26	8095	HTTP	Object detection service
Nemotron	8091	HTTP	LLM risk analysis service
Florence-2	8092	HTTP	Vision extraction service (optional)
CLIP	8093	HTTP	Re-identification service (optional)
Enrichment	8094	HTTP	Enrichment HTTP service (optional)
PostgreSQL	5432	TCP	Database
Redis	6379	TCP	Cache, queues, pub/sub

Frontend Port Details:

Production containers: nginx serves the built React app on internal ports 8080 (HTTP) and 8443 (HTTPS), mapped to host ports via FRONTEND_PORT (default 5173) and FRONTEND_HTTPS_PORT (default 8443)

Local development: Vite dev server runs on port 5173 (npm run dev in frontend/)

SSL: Enabled by default in production with auto-generated self-signed certificates. See SSL/HTTPS Configuration

Environment Variables¶

Complete reference: Environment Variable Reference

Quick Reference - Essential Variables¶

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection URL
`REDIS_URL`	No	`redis://localhost:6379/0`	Redis connection URL
`YOLO26_URL`	No	`http://localhost:8095`	YOLO26 service URL
`NEMOTRON_URL`	No	`http://localhost:8091`	Nemotron LLM service URL

Database Configuration¶

# Format
DATABASE_URL=postgresql+asyncpg://user:password@host:port/database  # pragma: allowlist secret

# Local development
DATABASE_URL=postgresql+asyncpg://security:password@localhost:5432/security  # pragma: allowlist secret

# Docker container (use service name)
DATABASE_URL=postgresql+asyncpg://security:password@postgres:5432/security  # pragma: allowlist secret

Important: There is no default DATABASE_URL. Run python setup.py to generate a .env file with secure credentials.

Redis Configuration¶

# Format
REDIS_URL=redis://[password@]host:port[/database]

# Local development
REDIS_URL=redis://localhost:6379/0

# Docker container
REDIS_URL=redis://redis:6379/0

AI Service URLs¶

Variable	Default	Description
`YOLO26_URL`	`http://localhost:8095`	YOLO26 object detection service
`NEMOTRON_URL`	`http://localhost:8091`	Nemotron LLM service
`FLORENCE_URL`	`http://localhost:8092`	Florence-2 vision-language (optional)
`CLIP_URL`	`http://localhost:8093`	CLIP embedding service (optional)
`ENRICHMENT_URL`	`http://localhost:8094`	Enrichment service (optional)

Warning: Use HTTPS in production to prevent MITM attacks.

AI Service Timeouts¶

Variable	Default	Range	Description
`AI_CONNECT_TIMEOUT`	`10.0`	1-60s	Connection timeout
`AI_HEALTH_TIMEOUT`	`5.0`	1-30s	Health check timeout
`YOLO26_READ_TIMEOUT`	`60.0`	10-300s	Detection response timeout
`NEMOTRON_READ_TIMEOUT`	`120.0`	30-600s	LLM response timeout

Batch Processing¶

Variable	Default	Description
`BATCH_WINDOW_SECONDS`	`90`	Max time window for grouping detections
`BATCH_IDLE_TIMEOUT_SECONDS`	`30`	Close batch after inactivity

Retention¶

Variable	Default	Description
`RETENTION_DAYS`	`30`	Days to keep events and detections
`LOG_RETENTION_DAYS`	`7`	Days to keep log entries

Camera Integration¶

Variable	Default	Description
`FOSCAM_BASE_PATH`	`/export/foscam`	Base directory for camera uploads

Camera images are expected at: {FOSCAM_BASE_PATH}/{camera_name}/

Frontend¶

Variable	Default	Description
`VITE_API_BASE_URL`	`http://localhost:8000`	Backend API URL
`VITE_WS_BASE_URL`	`ws://localhost:8000`	WebSocket URL
`FRONTEND_PORT`	`5173`	Host port for frontend container

For complete environment variable documentation, see Environment Variable Reference.

AI Service Deployment Modes¶

Development Mode (Host-run AI)¶

AI services run directly on the host while the backend runs in a container:

# macOS with Docker Desktop (default)
YOLO26_URL=http://host.docker.internal:8095
NEMOTRON_URL=http://host.docker.internal:8091

# macOS with Podman
export AI_HOST=host.containers.internal
podman-compose up -d

# Linux
# Use host IP or add --add-host=host.docker.internal:host-gateway

Production Mode (Fully Containerized)¶

All services including AI run in containers:

# Uses container network names (set in docker-compose.prod.yml)
YOLO26_URL=http://ai-yolo26:8095
NEMOTRON_URL=http://ai-llm:8091

Quick Reference: AI_HOST by Platform¶

Platform	Runtime	Development (host AI)	Production (container AI)
macOS	Docker	`host.docker.internal` (default)	N/A (use Linux for GPU)
macOS	Podman	`host.containers.internal`	N/A (use Linux for GPU)
Linux	Docker	Host IP or `host-gateway`	`ai-yolo26`, `ai-llm`, etc.
Linux	Podman	Host IP or `host-gateway`	`ai-yolo26`, `ai-llm`, etc.
Windows	Docker	`host.docker.internal`	N/A (use Linux for GPU)

Glossary¶

Key terms used throughout the documentation. Full glossary: Glossary

Core Concepts¶

Term	Definition
Detection	A single object instance identified by YOLO26 in an image. Contains object type, confidence score, bounding box, and timestamp.
Event	A security incident containing one or more detections, analyzed by Nemotron for risk assessment.
Batch	A collection of detections from a single camera grouped within a time window for analysis.
Risk Score	A numeric value from 0-100 assigned by Nemotron indicating the threat level of an event.
Risk Level	Categorical classification: Low (0-29), Medium (30-59), High (60-84), Critical (85-100).

AI Components¶

Term	Definition
YOLO26	Real-time object detection model using transformer architecture for accurate detection.
Nemotron	NVIDIA's LLM family. Production uses Nemotron-3-Nano-30B-A3B; development uses Mini 4B.
Florence-2	Vision-language model for extracting visual attributes (optional enrichment).
CLIP	Model for generating image embeddings enabling re-identification across camera frames.
Inference	The process of running an AI model on input data to produce predictions.

System Components¶

Term	Definition
Pipeline	End-to-end processing flow: File Watcher -> Detection -> Batch Aggregator -> Analysis -> Event
File Watcher	Service that monitors camera directories for new image uploads.
Batch Aggregator	Service that groups detections into batches based on camera and time proximity.
Circuit Breaker	Fault tolerance pattern that temporarily disables calls to a failing service.
Dead Letter Queue	Queue where failed messages are stored for investigation and reprocessing.

Troubleshooting¶

Quick symptom reference. Full guide: Troubleshooting Hub

Quick Self-Check¶

# 1. System health
curl -s http://localhost:8000/api/system/health | jq .

# 2. Service status
docker compose -f docker-compose.prod.yml ps

# 3. GPU status
nvidia-smi

# 4. Recent logs
docker compose -f docker-compose.prod.yml logs --tail=50 backend

Common Issues Quick Reference¶

Symptom	Likely Cause	Quick Fix
Dashboard shows no events	File watcher or AI down	Restart backend
Risk gauge stuck at 0	Nemotron unavailable	Start Nemotron LLM
Camera shows offline	FTP or folder path issue	Check FTP and folder config
AI not responding	Services not started	`./ai/start_detector.sh` and `./ai/start_llm.sh`
WebSocket disconnected	Backend down	Restart backend
"Connection refused" errors	Service not running	Start the service
CORS errors in browser	URL mismatch	Update `CORS_ORIGINS`

Detailed Troubleshooting Guides¶

Troubleshooting Index - Start here for any issue
AI Issues - YOLO26, Nemotron, pipeline problems
Connection Issues - Network, containers, WebSocket
Database Issues - PostgreSQL connection, migrations
GPU Issues - CUDA, VRAM, thermal issues

Configuration Files¶

File	Purpose
`.env`	Local environment overrides (not in git)
`.env.example`	Template with documented defaults
`data/runtime.env`	Runtime overrides (loaded after .env)
`docker-compose.yml`	Development Docker configuration
`docker-compose.prod.yml`	Production Docker configuration

Loading Order¶

Default values from backend/core/config.py
.env file (if exists)
data/runtime.env file (if exists)
Environment variables override all

Validation¶

Test your configuration:

# Check backend config loads correctly
cd backend
python -c "from core.config import get_settings; s = get_settings(); print(s.model_dump_json(indent=2))"

# Test service connectivity
curl http://localhost:8000/api/system/health     # Backend
curl http://localhost:8095/health                # YOLO26
curl http://localhost:8091/health                # Nemotron
redis-cli ping                                   # Redis

Subdirectories¶

API Documentation¶

REST and WebSocket API endpoint reference. Full API documentation is located in the Developer API Guide.

API Overview - API conventions and authentication
Core Resources - Cameras, events, detections, zones, entities, analytics
AI Pipeline - Enrichment, batches, AI audit, dead letter queue
System Operations - Health, config, alerts, logs, notifications
Real-time - WebSocket streams for events and system status
WebSocket Contracts - Detailed WebSocket message formats

config/¶

Configuration reference documentation.

Environment Variables - Complete variable reference
Risk Levels - Risk score ranges and severity

troubleshooting/¶

Symptom-based problem-solving guides.

Troubleshooting Index - Quick symptom lookup
AI Issues - AI service problems
Connection Issues - Network and connectivity
Database Issues - PostgreSQL problems
GPU Issues - GPU and CUDA issues

Operator Hub - System administration guides
Developer Hub - Development guides
User Hub - End-user documentation
Architecture - Technical architecture decisions

Back to Documentation | Operator Hub | Developer Hub