frigate/.cursor/components.md

# Frigate Components Deep Dive

## Backend Components (`frigate/`)

### Core Application

#### `app.py` - FrigateApp Class

**Purpose**: Central application orchestrator
**Key Responsibilities**:

- Process lifecycle management
- Resource initialization and cleanup
- Inter-process communication setup
- Database and embeddings initialization
- Hardware accelerator management

**Key Methods**:

- `start()`: System startup sequence
- `stop()`: Graceful shutdown
- `init_*()`: Component initialization methods
- `start_*()`: Process startup methods

#### `__main__.py` - Entry Point

**Purpose**: Application entry point and CLI handling
**Features**:

- Configuration validation
- Signal handling (SIGTERM)
- Error handling and user feedback

### API Layer (`api/`)

#### `app.py` - FastAPI Application Factory

**Purpose**: Web API and authentication
**Features**:

- FastAPI application creation
- Middleware configuration
- Route registration
- Error handling

#### `auth.py` - Authentication System

**Purpose**: User authentication and authorization
**Features**:

- JWT token generation/validation
- Password hashing
- User session management
- Login/logout endpoints

#### Route Modules

- **Events API**: Event CRUD operations, search, filtering
- **Media API**: Video/image serving, thumbnails
- **Config API**: Configuration management
- **Stats API**: System statistics and metrics
- **Export API**: Video export and download

### Configuration System (`config/`)

#### `config.py` - Main Configuration

**Purpose**: Central configuration management
**Features**:

- YAML parsing and validation
- Pydantic model integration
- Configuration migration
- Runtime validation

#### Camera Configuration (`camera/`)

- **`__init__.py`**: Camera-specific settings
- **`detect.py`**: Object detection configuration
- **`record.py`**: Recording settings
- **`motion.py`**: Motion detection parameters
- **`ffmpeg.py`**: FFmpeg stream configuration

#### Component Configs

- **`auth.py`**: Authentication settings
- **`mqtt.py`**: MQTT broker configuration
- **`database.py`**: Database connection settings
- **`ui.py`**: Web interface settings

### Object Detection (`detectors/`)

#### `detection_api.py` - Detection Interface

**Purpose**: Unified detection API
**Features**:

- Model loading and initialization
- Inference execution
- Result processing
- Hardware acceleration support

#### Detector Plugins (`plugins/`)

- **`cpu_tfl.py`**: CPU TensorFlow Lite
- **`edgetpu_tfl.py`**: Coral Edge TPU
- **`openvino.py`**: Intel OpenVINO
- **`tensorrt.py`**: NVIDIA TensorRT
- **`rknn.py`**: Rockchip NPU
- **`onnx.py`**: ONNX runtime

#### `detector_config.py` - Detector Configuration

**Purpose**: Detector-specific settings
**Features**:

- Model path configuration
- Input/output tensor mapping
- Hardware-specific parameters

### Video Processing

#### `video.py` - Video Capture and Processing

**Purpose**: Camera stream management
**Functions**:

- `capture_camera()`: Camera stream capture
- `track_camera()`: Object tracking
- Frame preprocessing
- Stream health monitoring

#### Motion Detection (`motion/`)

- **`frigate_motion.py`**: Basic motion detection
- **`improved_motion.py`**: Enhanced motion algorithms

### Event System (`events/`)

#### `maintainer.py` - Event Processor

**Purpose**: Event lifecycle management
**Features**:

- Event creation and updates
- Timeline generation
- Event cleanup
- Thumbnail generation

#### `cleanup.py` - Event Cleanup

**Purpose**: Automated data retention
**Features**:

- Old event removal
- Disk space management
- Configurable retention policies

#### `audio.py` - Audio Event Processing

**Purpose**: Audio-based event detection
**Features**:

- Audio stream processing
- Sound classification
- Audio event triggers

### Recording System (`record/`)

#### `record.py` - Recording Manager

**Purpose**: Video recording coordination
**Features**:

- Segment-based recording
- Retention policy enforcement
- Storage optimization
- Recovery handling

#### `cleanup.py` - Recording Cleanup

**Purpose**: Recording maintenance
**Features**:

- Old recording removal
- Storage quota management
- File integrity checks

#### `export.py` - Video Export

**Purpose**: Video export functionality
**Features**:

- Timeline-based exports
- Format conversion
- Progress tracking

### Communication (`comms/`)

#### `dispatcher.py` - Event Dispatcher

**Purpose**: Event distribution hub
**Features**:

- Multi-protocol communication
- Event routing
- Message formatting
- Error handling

#### `mqtt.py` - MQTT Client

**Purpose**: Home Assistant integration
**Features**:

- MQTT broker connection
- Topic management
- State publishing
- Discovery messages

#### `ws.py` - WebSocket Server

**Purpose**: Real-time web communication
**Features**:

- Live feed streaming
- Event notifications
- Bidirectional communication

#### Inter-Process Communication

- **`inter_process.py`**: Process messaging
- **`config_updater.py`**: Configuration updates
- **`zmq_proxy.py`**: ZeroMQ message routing

### Database (`db/`)

#### `sqlitevecq.py` - Vector Database

**Purpose**: Vector similarity search
**Features**:

- Embedding storage
- Similarity queries
- Vector indexing
- Semantic search

### Embeddings (`embeddings/`)

#### `embeddings.py` - Embedding Manager

**Purpose**: Feature extraction and management
**Features**:

- CLIP model integration
- Embedding generation
- Batch processing
- Index maintenance

#### `maintainer.py` - Embedding Maintenance

**Purpose**: Background embedding tasks
**Features**:

- Reindexing
- Cleanup
- Performance optimization

### Utilities (`util/`)

#### `image.py` - Image Processing

**Purpose**: Image manipulation utilities
**Features**:

- Shared memory frame management
- Image transformations
- Thumbnail generation
- Format conversions

#### `services.py` - System Services

**Purpose**: System integration utilities
**Features**:

- Hardware detection
- Service management
- Performance optimization

## Frontend Components (`web/src/`)

### Core Application

#### `App.tsx` - Main Application

**Purpose**: Root React component
**Features**:

- Routing configuration
- Global state management
- Error boundaries
- Theme providers

#### `index.css` - Global Styles

**Purpose**: Base styling and CSS variables
**Features**:

- TailwindCSS imports
- Theme definitions
- Global resets

### Components (`components/`)

#### Authentication (`auth/`)

- **`AuthForm.tsx`**: Login/logout forms

#### Camera Components (`camera/`)

- **`CameraImage.tsx`**: Static camera images
- **`AutoUpdatingCameraImage.tsx`**: Live camera feeds
- **`DebugCameraImage.tsx`**: Debug overlays

#### Player Components (`player/`)

- **`HlsVideoPlayer.tsx`**: HLS video playback
- **`BirdseyeLivePlayer.tsx`**: Multi-camera view
- **`GenericVideoPlayer.tsx`**: General video player

#### Event Components (`card/`)

- **`AnimatedEventCard.tsx`**: Event display cards
- **`ReviewCard.tsx`**: Review timeline cards
- **`ExportCard.tsx`**: Export status cards

#### Filter Components (`filter/`)

- **`CamerasFilterButton.tsx`**: Camera selection
- **`DatePickerContent.tsx`**: Date range picker
- **`FilterSwitch.tsx`**: Toggle filters
- **`ReviewFilterGroup.tsx`**: Review filters

#### Navigation (`navigation/`)

- **`Bottombar.tsx`**: Mobile navigation
- **`NavItem.tsx`**: Navigation items
- **`Sidebar.tsx`**: Desktop sidebar

#### UI Components (`ui/`)

- **Shadcn/ui components**: Buttons, dialogs, forms, etc.
- **Custom components**: Frigate-specific UI elements

### Pages (`pages/`)

#### `Live.tsx` - Live View

**Purpose**: Real-time camera monitoring
**Features**:

- Multi-camera grid
- Live detection overlays
- Camera controls
- Birdseye view

#### `Events.tsx` - Event Management

**Purpose**: Event browsing and management
**Features**:

- Event timeline
- Search and filtering
- Event details
- Export functionality

#### `Recordings.tsx` - Recording Playback

**Purpose**: Recorded video access
**Features**:

- Timeline scrubbing
- Multi-camera synchronization
- Export capabilities

#### `Settings.tsx` - System Configuration

**Purpose**: Configuration management
**Features**:

- Camera settings
- Detection configuration
- System preferences
- User management

### Hooks (`hooks/`)

#### API Integration

- **`use-api.ts`**: API client hooks
- **`use-websocket.ts`**: WebSocket management
- **`use-camera-activity.ts`**: Camera status

#### UI Utilities

- **`use-resize-observer.ts`**: Responsive layouts
- **`use-optimistic-state.ts`**: Optimistic updates
- **`use-intersection-observer.ts`**: Visibility detection

### Types (`types/`)

#### Core Types

- **`api.ts`**: API response types
- **`event.ts`**: Event data structures
- **`camera.ts`**: Camera configurations
- **`frigateConfig.ts`**: Configuration types

### Utilities (`utils/`)

#### Core Utilities

- **`browserUtil.ts`**: Browser compatibility
- **`colorUtil.ts`**: Color manipulation
- **`dateUtil.ts`**: Date formatting
- **`canvasUtil.ts`**: Canvas operations

## Infrastructure Components

### Docker Configuration (`docker/`)

#### Multi-Architecture Builds

- **`main/`**: Standard x86_64 build
- **`tensorrt/`**: NVIDIA GPU support
- **`rockchip/`**: ARM with NPU
- **`rpi/`**: Raspberry Pi optimized

#### Build Components

- **Base images**: Optimized runtime environments
- **Dependency installation**: Hardware-specific packages
- **Multi-stage builds**: Size optimization

### Process Management

#### S6 Overlay (`docker/main/rootfs/etc/s6-overlay/`)

- **Service definitions**: Process supervision
- **Startup scripts**: Initialization order
- **Health checks**: Process monitoring

## Component Interaction Patterns

### Data Flow Patterns

1. **Camera → Detection → Event → Storage**
2. **API Request → Validation → Processing → Response**
3. **Configuration → Validation → Distribution → Application**

### Communication Patterns

1. **Pub/Sub**: Event distribution via MQTT/WebSocket
2. **Request/Response**: API communications
3. **Shared Memory**: High-performance frame sharing
4. **Message Queues**: Asynchronous task processing

### Error Handling Patterns

1. **Circuit Breakers**: Prevent cascade failures
2. **Retry Logic**: Transient error recovery
3. **Graceful Degradation**: Partial functionality maintenance
4. **Error Boundaries**: React error isolation

This component structure enables modular development, testing, and maintenance while supporting the real-time requirements of video processing and object detection.