mirror of
https://github.com/blakeblackshear/frigate.git
synced 2026-04-27 17:17:40 +03:00
feat: added cursor rules
This commit is contained in:
skylineagle
parent
aabd5b0077
commit
22144a91d3
205
.cursor/README.md
Normal file
205
.cursor/README.md
Normal file
@ -0,0 +1,205 @@
|
||||
# .cursor Directory - Frigate Development Intelligence
|
||||
|
||||
This directory contains comprehensive documentation and rules for understanding and working with the Frigate repository. It's designed to help both AI assistants and developers quickly understand the codebase architecture, components, and development patterns.
|
||||
|
||||
## 📁 Directory Contents
|
||||
|
||||
### `rules`
|
||||
|
||||
**Core development rules and guidelines**
|
||||
|
||||
- Coding standards and style guidelines
|
||||
- Architecture principles and patterns
|
||||
- Technology stack specifications
|
||||
- Performance optimization rules
|
||||
- Security guidelines
|
||||
- File naming conventions
|
||||
- Common code patterns and examples
|
||||
|
||||
### `architecture.md`
|
||||
|
||||
**Deep-dive into Frigate's system architecture**
|
||||
|
||||
- High-level system overview
|
||||
- Component interaction diagrams
|
||||
- Data flow patterns
|
||||
- Database schema
|
||||
- Inter-process communication
|
||||
- Performance optimizations
|
||||
- Security architecture
|
||||
- Integration points
|
||||
|
||||
### `components.md`
|
||||
|
||||
**Detailed component mapping and responsibilities**
|
||||
|
||||
- Backend components (`frigate/`)
|
||||
- Frontend components (`web/`)
|
||||
- Infrastructure components
|
||||
- Component interaction patterns
|
||||
- API layer structure
|
||||
- Database models
|
||||
- Utility functions
|
||||
|
||||
### `development.md`
|
||||
|
||||
**Complete development guide**
|
||||
|
||||
- Environment setup instructions
|
||||
- Development workflow
|
||||
- Testing guidelines
|
||||
- Code patterns and examples
|
||||
- Debugging techniques
|
||||
- Docker development
|
||||
- Contributing guidelines
|
||||
- Common development tasks
|
||||
|
||||
## 🎯 Purpose
|
||||
|
||||
This directory serves as a **knowledge base** for:
|
||||
|
||||
1. **AI Assistants**: Quick understanding of codebase structure, patterns, and conventions
|
||||
2. **New Developers**: Comprehensive onboarding and development guide
|
||||
3. **Existing Contributors**: Reference for architecture decisions and patterns
|
||||
4. **Code Reviews**: Standards and patterns for consistent code quality
|
||||
|
||||
## 🏗️ Frigate Architecture Summary
|
||||
|
||||
**Frigate** is a complete local NVR (Network Video Recorder) with AI object detection:
|
||||
|
||||
### Core Technologies
|
||||
|
||||
- **Backend**: Python with FastAPI, multiprocessing, TensorFlow/OpenCV
|
||||
- **Frontend**: React 18+ with TypeScript, TailwindCSS, Vite
|
||||
- **Database**: SQLite with Peewee ORM, vector extensions for embeddings
|
||||
- **Infrastructure**: Docker, S6 overlay, Go2RTC streaming, hardware acceleration
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Real-time object detection** with multiple hardware accelerators
|
||||
- **Home Assistant integration** via MQTT
|
||||
- **Multi-camera support** with intelligent recording
|
||||
- **Web-based interface** for monitoring and configuration
|
||||
- **Semantic search** with AI-powered descriptions
|
||||
- **Hardware optimization** for Edge TPU, GPU acceleration
|
||||
|
||||
### Architecture Highlights
|
||||
|
||||
- **Multiprocess design** for real-time performance
|
||||
- **Shared memory** for efficient frame processing
|
||||
- **Event-driven communication** via ZMQ, MQTT, WebSockets
|
||||
- **Configuration-driven** with Pydantic validation
|
||||
- **Container-optimized** with multi-architecture support
|
||||
|
||||
## 🚀 Quick Start for Contributors
|
||||
|
||||
1. **Read the Rules**: Start with `rules` to understand coding standards
|
||||
2. **Understand Architecture**: Review `architecture.md` for system overview
|
||||
3. **Explore Components**: Use `components.md` to navigate the codebase
|
||||
4. **Follow Development Guide**: Use `development.md` for setup and workflow
|
||||
|
||||
## 🔧 Development Principles
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **Type Safety**: TypeScript frontend, Python type hints
|
||||
- **No Comments**: Self-documenting code with descriptive names
|
||||
- **Testing**: Comprehensive test coverage for critical paths
|
||||
- **Performance**: Real-time first, optimized for video processing
|
||||
|
||||
### Architecture Principles
|
||||
|
||||
- **Separation of Concerns**: Clear component boundaries
|
||||
- **Scalability**: Horizontal and vertical scaling support
|
||||
- **Reliability**: Graceful error handling and recovery
|
||||
- **Maintainability**: Modular design with clear interfaces
|
||||
|
||||
### Integration Focus
|
||||
|
||||
- **Home Assistant**: Primary integration target
|
||||
- **Hardware Acceleration**: Coral TPU, GPU support
|
||||
- **Real-time Processing**: Low-latency video and detection
|
||||
- **Local Processing**: Privacy-focused, no cloud dependencies
|
||||
|
||||
## 📚 Key Resources
|
||||
|
||||
### Official Documentation
|
||||
|
||||
- [Frigate Documentation](https://docs.frigate.video/)
|
||||
- [Installation Guide](https://docs.frigate.video/frigate/installation)
|
||||
- [Configuration Reference](https://docs.frigate.video/configuration/)
|
||||
- [API Documentation](https://docs.frigate.video/integrations/api)
|
||||
|
||||
### Development Resources
|
||||
|
||||
- [Contributing Guide](https://github.com/blakeblackshear/frigate/blob/master/docs/docs/development/contributing.md)
|
||||
- [Home Assistant Integration](https://docs.frigate.video/integrations/home-assistant)
|
||||
- [Hardware Recommendations](https://docs.frigate.video/frigate/hardware)
|
||||
|
||||
## 🎨 Code Style Highlights
|
||||
|
||||
### Python (Backend)
|
||||
|
||||
```python
|
||||
# Pydantic configuration models
|
||||
class CameraConfig(FrigateBaseModel):
|
||||
enabled: bool = Field(default=True)
|
||||
detect: DetectConfig = Field(default_factory=DetectConfig)
|
||||
|
||||
# Multiprocessing patterns
|
||||
class DetectionProcess(mp.Process):
|
||||
def run(self):
|
||||
while not self.stop_event.is_set():
|
||||
# Processing loop
|
||||
pass
|
||||
```
|
||||
|
||||
### TypeScript (Frontend)
|
||||
|
||||
```typescript
|
||||
// React component pattern
|
||||
interface ComponentProps {
|
||||
data: DataType;
|
||||
onAction: (id: string) => void;
|
||||
}
|
||||
|
||||
const Component = ({ data, onAction }: ComponentProps) => {
|
||||
const handleSubmit = () => {
|
||||
if (!data.id) return; // Early return pattern
|
||||
onAction(data.id);
|
||||
};
|
||||
|
||||
return (
|
||||
<button onClick={handleSubmit} className="tailwind-classes">
|
||||
Submit
|
||||
</button>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## 🔍 Finding Your Way Around
|
||||
|
||||
### Backend (`frigate/`)
|
||||
|
||||
- **`app.py`**: Main application orchestrator
|
||||
- **`api/`**: FastAPI REST endpoints
|
||||
- **`config/`**: Pydantic configuration system
|
||||
- **`detectors/`**: AI model integrations
|
||||
- **`events/`**: Event processing and management
|
||||
- **`video.py`**: Camera and video processing
|
||||
|
||||
### Frontend (`web/src/`)
|
||||
|
||||
- **`App.tsx`**: Root React component
|
||||
- **`components/`**: Reusable UI components
|
||||
- **`pages/`**: Route-level components
|
||||
- **`hooks/`**: Custom React hooks
|
||||
- **`types/`**: TypeScript type definitions
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- **`docker/`**: Multi-architecture container builds
|
||||
- **`migrations/`**: Database schema migrations
|
||||
- **`docs/`**: Documentation and guides
|
||||
|
||||
This `.cursor` directory provides everything needed to understand, contribute to, and maintain the Frigate codebase effectively.
|
||||
270
.cursor/architecture.md
Normal file
270
.cursor/architecture.md
Normal file
@ -0,0 +1,270 @@
|
||||
# Frigate Architecture Deep Dive
|
||||
|
||||
## System Overview
|
||||
|
||||
Frigate is a sophisticated Network Video Recorder (NVR) with real-time AI object detection, designed specifically for Home Assistant integration. The system uses a multi-process architecture to achieve real-time performance while maintaining stability and resource efficiency.
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Frigate System │
|
||||
├─────────────────┬─────────────────┬─────────────────────────────┤
|
||||
│ Web Frontend │ Python Core │ Infrastructure │
|
||||
│ (React/TS) │ (FastAPI) │ (Docker/Nginx) │
|
||||
└─────────────────┴─────────────────┴─────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Python Backend (`frigate/`)
|
||||
|
||||
#### Main Application (`app.py`)
|
||||
|
||||
- **FrigateApp Class**: Central orchestrator managing all system processes
|
||||
- **Process Management**: Spawns and manages detection, recording, cleanup processes
|
||||
- **Resource Management**: Handles shared memory, queues, and inter-process communication
|
||||
- **Service Lifecycle**: Manages startup, shutdown, and error recovery
|
||||
|
||||
#### API Layer (`api/`)
|
||||
|
||||
- **FastAPI Application**: Modern async Python web framework
|
||||
- **Authentication**: JWT-based auth with user management
|
||||
- **RESTful Endpoints**: Full CRUD operations for events, recordings, configuration
|
||||
- **WebSocket Support**: Real-time communication for live feeds and notifications
|
||||
- **OpenAPI Documentation**: Auto-generated API documentation
|
||||
|
||||
#### Configuration System (`config/`)
|
||||
|
||||
- **Pydantic Models**: Type-safe configuration with validation
|
||||
- **YAML Support**: Human-readable configuration files
|
||||
- **Runtime Validation**: Ensures configuration integrity
|
||||
- **Hot Reloading**: Dynamic configuration updates without restart
|
||||
|
||||
#### Object Detection (`object_detection.py`, `detectors/`)
|
||||
|
||||
- **TensorFlow Integration**: Deep learning model execution
|
||||
- **Hardware Acceleration**: Support for Coral TPU, NVIDIA GPU, Intel GPU
|
||||
- **Multi-Model Support**: Different detectors for different use cases
|
||||
- **Process Isolation**: Detection runs in separate processes for stability
|
||||
|
||||
#### Video Processing (`video/`, `motion/`)
|
||||
|
||||
- **Camera Management**: RTSP/HTTP stream handling
|
||||
- **Motion Detection**: Efficient OpenCV-based motion detection
|
||||
- **Frame Processing**: Shared memory frame management
|
||||
- **Recording**: Segment-based video recording with retention policies
|
||||
|
||||
#### Event System (`events/`)
|
||||
|
||||
- **Event Processing**: Real-time event detection and classification
|
||||
- **Timeline Management**: Chronological event organization
|
||||
- **Cleanup Processes**: Automated old data removal
|
||||
- **Embeddings**: Vector similarity search for event matching
|
||||
|
||||
#### Communication (`comms/`)
|
||||
|
||||
- **MQTT Integration**: Home Assistant and IoT device communication
|
||||
- **WebSocket Server**: Real-time web interface updates
|
||||
- **ZMQ Messaging**: Inter-process communication
|
||||
- **Dispatcher Pattern**: Event distribution to multiple consumers
|
||||
|
||||
### 2. Web Frontend (`web/`)
|
||||
|
||||
#### React Application
|
||||
|
||||
- **Modern React 18+**: Functional components with hooks
|
||||
- **TypeScript**: Full type safety throughout the frontend
|
||||
- **Component Architecture**: Modular, reusable components
|
||||
- **State Management**: Context providers and custom hooks
|
||||
|
||||
#### UI Framework
|
||||
|
||||
- **TailwindCSS**: Utility-first CSS framework
|
||||
- **Shadcn/ui**: High-quality component library
|
||||
- **Responsive Design**: Mobile-first responsive layout
|
||||
- **Accessibility**: ARIA labels and keyboard navigation
|
||||
|
||||
#### Real-time Features
|
||||
|
||||
- **WebSocket Client**: Live feed streaming
|
||||
- **Server-Sent Events**: Real-time notifications
|
||||
- **Progressive Loading**: Efficient data fetching
|
||||
- **Offline Support**: Graceful degradation
|
||||
|
||||
#### Key Pages
|
||||
|
||||
- **Live View**: Real-time camera feeds with detection overlays
|
||||
- **Events**: Searchable event timeline with filtering
|
||||
- **Recordings**: Video playback and export functionality
|
||||
- **Settings**: Configuration management interface
|
||||
|
||||
### 3. Infrastructure
|
||||
|
||||
#### Docker Architecture
|
||||
|
||||
- **Multi-stage Builds**: Optimized container images
|
||||
- **Multi-architecture**: Support for AMD64, ARM64, ARM32
|
||||
- **Hardware-specific**: Specialized builds for Coral, NVIDIA, etc.
|
||||
- **Development**: DevContainer support for consistent development
|
||||
|
||||
#### Process Management (S6 Overlay)
|
||||
|
||||
- **Service Supervision**: Automatic process restart on failure
|
||||
- **Graceful Shutdown**: Proper cleanup on container stop
|
||||
- **Logging**: Centralized log management
|
||||
- **Health Monitoring**: Container health checks
|
||||
|
||||
#### Streaming (Go2RTC)
|
||||
|
||||
- **RTSP Server**: Re-streaming to reduce camera connections
|
||||
- **WebRTC Support**: Low-latency browser streaming
|
||||
- **Protocol Conversion**: Multiple streaming protocol support
|
||||
- **Transcoding**: Hardware-accelerated video processing
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Video Processing Pipeline
|
||||
|
||||
```
|
||||
Camera → Go2RTC → Motion Detection → Object Detection → Event Creation → Storage
|
||||
↓
|
||||
Live Stream → WebSocket → Frontend
|
||||
```
|
||||
|
||||
### Event Processing Flow
|
||||
|
||||
```
|
||||
Detection → Event Processor → Timeline → Database
|
||||
↓
|
||||
MQTT/WebSocket → Home Assistant/Frontend
|
||||
```
|
||||
|
||||
### Configuration Flow
|
||||
|
||||
```
|
||||
YAML Config → Pydantic Validation → Runtime Config → Process Distribution
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Core Tables
|
||||
|
||||
- **Events**: Object detection events with metadata
|
||||
- **Recordings**: Video recording segments
|
||||
- **ReviewSegment**: Motion-based review segments
|
||||
- **Timeline**: Chronological event timeline
|
||||
- **Previews**: Thumbnail previews for recordings
|
||||
|
||||
### Vector Database
|
||||
|
||||
- **Embeddings**: Semantic search capabilities
|
||||
- **Similarity**: Find similar events/objects
|
||||
- **Reindexing**: Background embedding updates
|
||||
|
||||
## Inter-Process Communication
|
||||
|
||||
### Message Queues
|
||||
|
||||
- **Detection Queue**: Frame processing requests
|
||||
- **Event Queue**: Event notifications
|
||||
- **Config Updates**: Runtime configuration changes
|
||||
|
||||
### Shared Memory
|
||||
|
||||
- **Frame Buffers**: Raw video frame data
|
||||
- **Detection Results**: Object detection outputs
|
||||
- **Statistics**: Real-time performance metrics
|
||||
|
||||
### ZeroMQ Patterns
|
||||
|
||||
- **Publisher/Subscriber**: Event distribution
|
||||
- **Request/Reply**: Configuration queries
|
||||
- **Push/Pull**: Work distribution
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### CPU Optimization
|
||||
|
||||
- **Multiprocessing**: Separate processes for I/O vs CPU tasks
|
||||
- **Process Affinity**: CPU core assignment for critical processes
|
||||
- **Queue Management**: Efficient message passing
|
||||
- **Memory Pools**: Reduced allocation overhead
|
||||
|
||||
### Hardware Acceleration
|
||||
|
||||
- **Coral TPU**: Edge TPU inference acceleration
|
||||
- **NVIDIA GPU**: CUDA-based processing
|
||||
- **Intel GPU**: Intel GPU acceleration
|
||||
- **Hardware Decoding**: GPU-accelerated video decoding
|
||||
|
||||
### Memory Management
|
||||
|
||||
- **Shared Memory**: Zero-copy frame passing
|
||||
- **Object Pools**: Reused detection objects
|
||||
- **Garbage Collection**: Efficient memory cleanup
|
||||
- **Memory Mapping**: Direct file access
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### Authentication
|
||||
|
||||
- **JWT Tokens**: Stateless authentication
|
||||
- **User Management**: Role-based access control
|
||||
- **Session Management**: Secure session handling
|
||||
- **API Security**: Endpoint protection
|
||||
|
||||
### Data Protection
|
||||
|
||||
- **Input Validation**: Pydantic model validation
|
||||
- **SQL Injection Prevention**: ORM-based queries
|
||||
- **File Path Sanitization**: Secure file access
|
||||
- **CORS Configuration**: Cross-origin protection
|
||||
|
||||
## Monitoring and Observability
|
||||
|
||||
### Metrics Collection
|
||||
|
||||
- **System Stats**: CPU, memory, disk usage
|
||||
- **Camera Stats**: FPS, detection rates
|
||||
- **Process Health**: Process status monitoring
|
||||
- **Performance Metrics**: Latency, throughput
|
||||
|
||||
### Logging
|
||||
|
||||
- **Structured Logging**: JSON-formatted logs
|
||||
- **Log Levels**: Configurable verbosity
|
||||
- **Log Rotation**: Automatic log management
|
||||
- **Error Tracking**: Exception monitoring
|
||||
|
||||
## Scalability Considerations
|
||||
|
||||
### Horizontal Scaling
|
||||
|
||||
- **Process Distribution**: Multiple detection processes
|
||||
- **Camera Distribution**: Cameras across processes
|
||||
- **Load Balancing**: Request distribution
|
||||
|
||||
### Vertical Scaling
|
||||
|
||||
- **Multi-threading**: Thread-safe operations
|
||||
- **Resource Allocation**: Dynamic resource assignment
|
||||
- **Queue Sizing**: Configurable queue depths
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Home Assistant
|
||||
|
||||
- **MQTT Discovery**: Automatic entity creation
|
||||
- **State Updates**: Real-time state synchronization
|
||||
- **Service Calls**: Action integration
|
||||
- **Notification System**: Event notifications
|
||||
|
||||
### External APIs
|
||||
|
||||
- **Frigate+**: Cloud-based model training
|
||||
- **GenAI Integration**: AI-powered descriptions
|
||||
- **Webhooks**: External event notifications
|
||||
- **Third-party Integrations**: Plugin architecture
|
||||
|
||||
This architecture prioritizes real-time performance, reliability, and ease of integration while maintaining modularity and extensibility for future enhancements.
|
||||
474
.cursor/components.md
Normal file
474
.cursor/components.md
Normal file
@ -0,0 +1,474 @@
|
||||
# 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.
|
||||
556
.cursor/development.md
Normal file
556
.cursor/development.md
Normal file
@ -0,0 +1,556 @@
|
||||
# Frigate Development Guide
|
||||
|
||||
## Development Environment Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Docker**: For containerized development
|
||||
- **Python 3.11+**: Backend development
|
||||
- **Node.js 20+**: Frontend development
|
||||
- **Bun**: Package manager (preferred over npm)
|
||||
- **Git**: Version control
|
||||
|
||||
### Development Container (Recommended)
|
||||
|
||||
The repository includes a devcontainer configuration for consistent development:
|
||||
|
||||
```bash
|
||||
# Open in VS Code with Dev Containers extension
|
||||
code .
|
||||
# Select "Reopen in Container" when prompted
|
||||
```
|
||||
|
||||
### Local Development Setup
|
||||
|
||||
#### Backend Setup
|
||||
|
||||
```bash
|
||||
# Install Python dependencies
|
||||
cd frigate/
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Set up pre-commit hooks
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
#### Frontend Setup
|
||||
|
||||
```bash
|
||||
# Install frontend dependencies
|
||||
cd web/
|
||||
bun install
|
||||
|
||||
# Start development server
|
||||
PROXY_HOST=localhost:5000 bun run dev
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Code Style and Quality
|
||||
|
||||
#### Python
|
||||
|
||||
- **Formatter**: Black (line length: 88)
|
||||
- **Import Sorting**: isort
|
||||
- **Linting**: flake8, pylint
|
||||
- **Type Checking**: mypy
|
||||
- **Testing**: pytest
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
black frigate/
|
||||
isort frigate/
|
||||
|
||||
# Run linting
|
||||
flake8 frigate/
|
||||
mypy frigate/
|
||||
|
||||
# Run tests
|
||||
pytest frigate/test/
|
||||
```
|
||||
|
||||
#### TypeScript/React
|
||||
|
||||
- **Formatter**: Prettier
|
||||
- **Linting**: ESLint with TypeScript rules
|
||||
- **Type Checking**: TypeScript compiler
|
||||
|
||||
```bash
|
||||
# Format and lint
|
||||
cd web/
|
||||
bun run lint
|
||||
bun run format
|
||||
|
||||
# Type checking
|
||||
bun run type-check
|
||||
|
||||
# Run tests
|
||||
bun run test
|
||||
```
|
||||
|
||||
### Testing Guidelines
|
||||
|
||||
#### Backend Testing
|
||||
|
||||
```python
|
||||
# Test file structure: frigate/test/
|
||||
# Example test file: test_config.py
|
||||
|
||||
import pytest
|
||||
from frigate.config import FrigateConfig
|
||||
|
||||
def test_config_validation():
|
||||
# Test configuration validation
|
||||
pass
|
||||
|
||||
def test_api_endpoint():
|
||||
# Test API endpoints
|
||||
pass
|
||||
|
||||
# Use fixtures for common setup
|
||||
@pytest.fixture
|
||||
def test_config():
|
||||
return FrigateConfig.load_file("test_config.yml")
|
||||
```
|
||||
|
||||
#### Frontend Testing
|
||||
|
||||
```typescript
|
||||
// Test file structure: web/src/**/*.test.tsx
|
||||
// Example: components/Button.test.tsx
|
||||
|
||||
import { render, screen } from "@testing-library/react";
|
||||
import { Button } from "./Button";
|
||||
|
||||
test("renders button with text", () => {
|
||||
render(<Button>Click me</Button>);
|
||||
expect(screen.getByText("Click me")).toBeInTheDocument();
|
||||
});
|
||||
```
|
||||
|
||||
### Component Development Patterns
|
||||
|
||||
#### Python Process Pattern
|
||||
|
||||
```python
|
||||
import multiprocessing as mp
|
||||
from multiprocessing.synchronize import Event as MpEvent
|
||||
import logging
|
||||
|
||||
class MyProcess(mp.Process):
|
||||
def __init__(self, config: dict, stop_event: MpEvent):
|
||||
super().__init__()
|
||||
self.config = config
|
||||
self.stop_event = stop_event
|
||||
self.logger = logging.getLogger(__name__)
|
||||
|
||||
def run(self):
|
||||
"""Main process loop"""
|
||||
self.logger.info("Starting process")
|
||||
|
||||
while not self.stop_event.is_set():
|
||||
try:
|
||||
# Main processing logic
|
||||
self.process_frame()
|
||||
|
||||
except Exception as e:
|
||||
self.logger.error(f"Error in process: {e}")
|
||||
|
||||
self.logger.info("Process stopped")
|
||||
|
||||
def process_frame(self):
|
||||
"""Process individual frames"""
|
||||
pass
|
||||
```
|
||||
|
||||
#### React Component Pattern
|
||||
|
||||
```typescript
|
||||
interface ComponentProps {
|
||||
data: DataType;
|
||||
onAction: (id: string) => void;
|
||||
className?: string;
|
||||
}
|
||||
|
||||
const Component = ({ data, onAction, className }: ComponentProps) => {
|
||||
const [loading, setLoading] = useState(false);
|
||||
|
||||
// Event handler with handle prefix
|
||||
const handleSubmit = async () => {
|
||||
// Early return pattern
|
||||
if (loading) return;
|
||||
|
||||
setLoading(true);
|
||||
try {
|
||||
await onAction(data.id);
|
||||
} catch (error) {
|
||||
console.error("Action failed:", error);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<div className={cn("base-classes", className)}>
|
||||
<button
|
||||
onClick={handleSubmit}
|
||||
disabled={loading}
|
||||
className="button-classes"
|
||||
aria-label="Submit action"
|
||||
>
|
||||
{loading ? "Loading..." : "Submit"}
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
#### Configuration Model Pattern
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel, Field, field_validator
|
||||
from typing import Optional
|
||||
|
||||
class ComponentConfig(BaseModel):
|
||||
enabled: bool = Field(default=True, description="Enable component")
|
||||
threshold: float = Field(default=0.5, ge=0.0, le=1.0)
|
||||
name: Optional[str] = Field(default=None)
|
||||
|
||||
@field_validator('name')
|
||||
def validate_name(cls, v):
|
||||
if v is not None and len(v) < 1:
|
||||
raise ValueError("Name must not be empty")
|
||||
return v
|
||||
|
||||
class Config:
|
||||
extra = "forbid" # Prevent additional fields
|
||||
```
|
||||
|
||||
### API Development
|
||||
|
||||
#### FastAPI Endpoint Pattern
|
||||
|
||||
```python
|
||||
from fastapi import APIRouter, Depends, HTTPException
|
||||
from pydantic import BaseModel
|
||||
from typing import List
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
class ResponseModel(BaseModel):
|
||||
id: str
|
||||
name: str
|
||||
status: str
|
||||
|
||||
@router.get("/items", response_model=List[ResponseModel])
|
||||
async def get_items(
|
||||
limit: int = 10,
|
||||
current_user = Depends(get_current_user)
|
||||
):
|
||||
"""Get list of items"""
|
||||
try:
|
||||
items = await fetch_items(limit)
|
||||
return [ResponseModel(**item) for item in items]
|
||||
except Exception as e:
|
||||
raise HTTPException(status_code=500, detail=str(e))
|
||||
|
||||
@router.post("/items/{item_id}/action")
|
||||
async def perform_action(
|
||||
item_id: str,
|
||||
current_user = Depends(get_current_user)
|
||||
):
|
||||
"""Perform action on item"""
|
||||
# Implementation
|
||||
return {"status": "success"}
|
||||
```
|
||||
|
||||
### Database Development
|
||||
|
||||
#### Model Definition
|
||||
|
||||
```python
|
||||
from peewee import *
|
||||
from frigate.models import Model
|
||||
|
||||
class NewModel(Model):
|
||||
id = AutoField()
|
||||
name = CharField(max_length=100, unique=True)
|
||||
created_at = DateTimeField(default=datetime.now)
|
||||
data = JSONField()
|
||||
|
||||
class Meta:
|
||||
table_name = 'new_model'
|
||||
indexes = (
|
||||
(('name', 'created_at'), False),
|
||||
)
|
||||
```
|
||||
|
||||
#### Migration Pattern
|
||||
|
||||
```python
|
||||
# migrations/XXX_add_new_feature.py
|
||||
|
||||
def migrate(migrator, database, fake=False, **kwargs):
|
||||
"""Migration logic"""
|
||||
migrator.add_column('events', 'new_field', CharField(null=True))
|
||||
|
||||
def rollback(migrator, database, fake=False, **kwargs):
|
||||
"""Rollback logic"""
|
||||
migrator.drop_column('events', 'new_field')
|
||||
```
|
||||
|
||||
### Real-time Features
|
||||
|
||||
#### WebSocket Integration
|
||||
|
||||
```typescript
|
||||
// Frontend WebSocket hook
|
||||
import { useWebSocket } from "@/hooks/use-websocket";
|
||||
|
||||
const Component = () => {
|
||||
const { socket, connected } = useWebSocket();
|
||||
|
||||
useEffect(() => {
|
||||
if (!socket) return;
|
||||
|
||||
const handleEvent = (data: EventData) => {
|
||||
// Handle real-time event
|
||||
};
|
||||
|
||||
socket.on("event", handleEvent);
|
||||
return () => socket.off("event", handleEvent);
|
||||
}, [socket]);
|
||||
|
||||
return <div>Status: {connected ? "Connected" : "Disconnected"}</div>;
|
||||
};
|
||||
```
|
||||
|
||||
#### Python WebSocket Handler
|
||||
|
||||
```python
|
||||
from frigate.comms.ws import WebSocket
|
||||
|
||||
class EventWebSocket(WebSocket):
|
||||
def on_connect(self):
|
||||
"""Handle client connection"""
|
||||
self.send_json({"type": "connected"})
|
||||
|
||||
def on_message(self, message):
|
||||
"""Handle incoming message"""
|
||||
if message["type"] == "subscribe":
|
||||
self.subscribe_to_events()
|
||||
|
||||
def send_event(self, event_data):
|
||||
"""Send event to client"""
|
||||
self.send_json({
|
||||
"type": "event",
|
||||
"data": event_data
|
||||
})
|
||||
```
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
#### Shared Memory Usage
|
||||
|
||||
```python
|
||||
import multiprocessing as mp
|
||||
from frigate.util.image import SharedMemoryFrameManager
|
||||
|
||||
class FrameProcessor:
|
||||
def __init__(self):
|
||||
self.frame_manager = SharedMemoryFrameManager()
|
||||
|
||||
def process_frame(self, camera_name: str, frame_data: bytes):
|
||||
# Store frame in shared memory
|
||||
frame_id = self.frame_manager.create(
|
||||
camera_name,
|
||||
frame_data.shape,
|
||||
frame_data.dtype
|
||||
)
|
||||
|
||||
# Copy frame data
|
||||
shm_frame = self.frame_manager.get(frame_id)
|
||||
shm_frame[:] = frame_data
|
||||
|
||||
return frame_id
|
||||
```
|
||||
|
||||
#### Frontend Performance
|
||||
|
||||
```typescript
|
||||
// Use React.memo for expensive components
|
||||
const ExpensiveComponent = React.memo(({ data }: Props) => {
|
||||
return <div>{/* Expensive rendering */}</div>;
|
||||
});
|
||||
|
||||
// Use useMemo for expensive calculations
|
||||
const ProcessedData = ({ rawData }: Props) => {
|
||||
const processedData = useMemo(() => {
|
||||
return expensiveProcessing(rawData);
|
||||
}, [rawData]);
|
||||
|
||||
return <div>{processedData}</div>;
|
||||
};
|
||||
|
||||
// Use useCallback for stable references
|
||||
const Parent = () => {
|
||||
const handleAction = useCallback((id: string) => {
|
||||
// Handle action
|
||||
}, []);
|
||||
|
||||
return <Child onAction={handleAction} />;
|
||||
};
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
#### Python Debugging
|
||||
|
||||
```python
|
||||
import logging
|
||||
import pdb
|
||||
|
||||
# Set up detailed logging
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
def debug_function():
|
||||
logger.debug("Debug information")
|
||||
|
||||
# Set breakpoint for debugging
|
||||
pdb.set_trace()
|
||||
|
||||
# Process continues...
|
||||
```
|
||||
|
||||
#### Frontend Debugging
|
||||
|
||||
```typescript
|
||||
// Use React Developer Tools
|
||||
// Add debugging props in development
|
||||
const DebugComponent = ({ data }: Props) => {
|
||||
useEffect(() => {
|
||||
if (process.env.NODE_ENV === "development") {
|
||||
console.log("Component data:", data);
|
||||
}
|
||||
}, [data]);
|
||||
|
||||
return <div>{/* Component content */}</div>;
|
||||
};
|
||||
```
|
||||
|
||||
### Docker Development
|
||||
|
||||
#### Development Dockerfile
|
||||
|
||||
```dockerfile
|
||||
FROM frigate:dev as dev
|
||||
|
||||
# Install development dependencies
|
||||
RUN pip install debugpy pytest-cov
|
||||
|
||||
# Enable development features
|
||||
ENV PYTHONPATH=/workspace/frigate
|
||||
ENV FRIGATE_CONFIG_FILE=/config/config.yml
|
||||
|
||||
# Expose debug port
|
||||
EXPOSE 5678
|
||||
|
||||
CMD ["python", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "-m", "frigate"]
|
||||
```
|
||||
|
||||
#### Docker Compose for Development
|
||||
|
||||
```yaml
|
||||
version: "3.8"
|
||||
services:
|
||||
frigate:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: docker/main/Dockerfile
|
||||
target: devcontainer
|
||||
volumes:
|
||||
- .:/workspace/frigate
|
||||
- ./config:/config
|
||||
ports:
|
||||
- "5000:5000" # Web interface
|
||||
- "5678:5678" # Debug port
|
||||
environment:
|
||||
- PYTHONPATH=/workspace/frigate
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
#### Test Configuration
|
||||
|
||||
```yaml
|
||||
# test_config.yml
|
||||
cameras:
|
||||
test_camera:
|
||||
ffmpeg:
|
||||
inputs:
|
||||
- path: /dev/video0
|
||||
roles: [detect]
|
||||
detect:
|
||||
enabled: true
|
||||
|
||||
detectors:
|
||||
cpu:
|
||||
type: cpu
|
||||
```
|
||||
|
||||
#### End-to-End Testing
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from frigate.app import FrigateApp
|
||||
from frigate.config import FrigateConfig
|
||||
|
||||
@pytest.fixture
|
||||
def test_app():
|
||||
config = FrigateConfig.load_file("test_config.yml")
|
||||
app = FrigateApp(config)
|
||||
yield app
|
||||
app.stop()
|
||||
|
||||
def test_detection_pipeline(test_app):
|
||||
# Test full detection pipeline
|
||||
pass
|
||||
```
|
||||
|
||||
### Contributing Guidelines
|
||||
|
||||
1. **Fork and Clone**: Fork the repository and clone locally
|
||||
2. **Branch**: Create feature branches from master
|
||||
3. **Develop**: Follow coding standards and patterns
|
||||
4. **Test**: Write and run tests for new features
|
||||
5. **Document**: Update documentation as needed
|
||||
6. **Pull Request**: Submit PR with clear description
|
||||
7. **Review**: Address review feedback promptly
|
||||
|
||||
### Common Development Tasks
|
||||
|
||||
#### Adding a New Detector
|
||||
|
||||
1. Create detector plugin in `frigate/detectors/plugins/`
|
||||
2. Add configuration model in `frigate/detectors/detector_config.py`
|
||||
3. Update detector factory in `frigate/detectors/__init__.py`
|
||||
4. Add tests and documentation
|
||||
|
||||
#### Adding a New API Endpoint
|
||||
|
||||
1. Define request/response models with Pydantic
|
||||
2. Create endpoint in appropriate router module
|
||||
3. Add authentication/authorization if needed
|
||||
4. Write tests for the endpoint
|
||||
5. Update API documentation
|
||||
|
||||
#### Adding a New React Component
|
||||
|
||||
1. Create component in appropriate directory
|
||||
2. Define TypeScript interfaces for props
|
||||
3. Implement with proper error handling
|
||||
4. Add to component exports
|
||||
5. Write tests and stories (if using Storybook)
|
||||
|
||||
This development guide provides the foundation for contributing to Frigate while maintaining code quality and architectural consistency.
|
||||
239
.cursor/rules
Normal file
239
.cursor/rules
Normal file
@ -0,0 +1,239 @@
|
||||
# Frigate Repository Rules and Guidelines
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
Frigate is a complete and local NVR (Network Video Recorder) designed for Home Assistant with AI object detection. It consists of:
|
||||
|
||||
### Core Technologies Stack
|
||||
|
||||
1. **Backend**: Python-based with FastAPI
|
||||
|
||||
- Object detection using TensorFlow/OpenCV
|
||||
- Multiprocessing architecture for real-time performance
|
||||
- SQLite database with Peewee ORM
|
||||
- MQTT communication
|
||||
- Docker containerization
|
||||
|
||||
2. **Frontend**: Modern React/TypeScript SPA
|
||||
|
||||
- React 18+ with TypeScript
|
||||
- TailwindCSS for styling
|
||||
- Shadcn/ui components
|
||||
- Vite build system
|
||||
- WebSocket real-time communication
|
||||
|
||||
3. **Infrastructure**:
|
||||
- Docker multi-stage builds
|
||||
- Nginx for serving
|
||||
- S6 overlay for process management
|
||||
- Go2RTC for streaming
|
||||
- Hardware acceleration support (Coral TPU, GPU)
|
||||
|
||||
## Project Structure Rules
|
||||
|
||||
### Python Backend (`frigate/`)
|
||||
|
||||
- **Main Application**: `frigate/app.py` - Central FrigateApp class managing all services
|
||||
- **API Layer**: `frigate/api/` - FastAPI-based REST API with Pydantic models
|
||||
- **Configuration**: `frigate/config/` - Pydantic-based configuration system
|
||||
- **Detection**: Object detection processes and AI model integration
|
||||
- **Events**: Event processing, cleanup, and management
|
||||
- **Video**: Camera capture, motion detection, and video processing
|
||||
- **Database**: SQLite with vector extensions for embeddings
|
||||
- **Communication**: Inter-process communication via ZMQ, MQTT, WebSockets
|
||||
|
||||
### Frontend (`web/`)
|
||||
|
||||
- **Components**: React components organized by feature
|
||||
- **Pages**: Top-level route components
|
||||
- **Hooks**: Custom React hooks for API integration
|
||||
- **Types**: TypeScript type definitions
|
||||
- **Utils**: Utility functions and helpers
|
||||
|
||||
### Docker (`docker/`)
|
||||
|
||||
- Multi-architecture support (AMD64, ARM64, etc.)
|
||||
- Hardware-specific builds (Coral, NVIDIA, etc.)
|
||||
- Development container support
|
||||
|
||||
## Development Rules
|
||||
|
||||
### Python Development
|
||||
|
||||
1. Use Pydantic for all configuration and data models
|
||||
2. Leverage multiprocessing for CPU-intensive tasks
|
||||
3. Follow async/await patterns for I/O operations
|
||||
4. Use structured logging with appropriate log levels
|
||||
5. Implement proper error handling and recovery
|
||||
6. Use type hints consistently
|
||||
|
||||
### Frontend Development
|
||||
|
||||
1. Use TypeScript for all new code
|
||||
2. Follow React functional component patterns with hooks
|
||||
3. Use TailwindCSS classes exclusively for styling
|
||||
4. Implement proper error boundaries
|
||||
5. Use const assertions for immutable data
|
||||
6. Prefer early returns in component logic
|
||||
7. Name event handlers with "handle" prefix (handleClick, handleSubmit)
|
||||
8. Use descriptive variable and function names
|
||||
|
||||
### API Development
|
||||
|
||||
1. Use Pydantic models for request/response validation
|
||||
2. Implement proper HTTP status codes
|
||||
3. Use FastAPI dependency injection
|
||||
4. Document all endpoints with OpenAPI schemas
|
||||
5. Implement proper authentication/authorization
|
||||
|
||||
### Testing Rules
|
||||
|
||||
1. Write unit tests for critical business logic
|
||||
2. Use pytest for Python testing
|
||||
3. Mock external dependencies appropriately
|
||||
4. Test configuration validation thoroughly
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Python
|
||||
|
||||
- Follow PEP 8 style guidelines
|
||||
- Use Black for code formatting
|
||||
- Use isort for import organization
|
||||
- Maximum line length: 88 characters
|
||||
- Use f-strings for string formatting
|
||||
|
||||
### TypeScript/React
|
||||
|
||||
- Use ESLint with strict TypeScript rules
|
||||
- Use Prettier for code formatting
|
||||
- Prefer interface over type for object definitions
|
||||
- Use PascalCase for components, camelCase for functions/variables
|
||||
- Implement accessibility features (ARIA labels, keyboard navigation)
|
||||
|
||||
### Comments and Documentation
|
||||
|
||||
- COMMENTS ARE NOT ALLOWED ANYWHERE - code should be self-documenting
|
||||
- Use descriptive names instead of explanatory comments
|
||||
- Document complex algorithms in external documentation
|
||||
|
||||
## Performance Rules
|
||||
|
||||
1. **Real-time First**: Prioritize real-time performance over processing every frame
|
||||
2. **Multiprocessing**: Use separate processes for detection, recording, and web serving
|
||||
3. **Memory Management**: Use shared memory for frame data between processes
|
||||
4. **Resource Optimization**: Monitor CPU, memory, and GPU usage
|
||||
5. **Hardware Acceleration**: Leverage Coral TPU, GPU acceleration when available
|
||||
|
||||
## Security Guidelines
|
||||
|
||||
1. Implement proper authentication for web interface
|
||||
2. Validate all user inputs through Pydantic models
|
||||
3. Use environment variables for sensitive configuration
|
||||
4. Implement proper CORS policies
|
||||
5. Sanitize file paths and user uploads
|
||||
|
||||
## Database Guidelines
|
||||
|
||||
1. Use Peewee ORM for database operations
|
||||
2. Implement proper migrations for schema changes
|
||||
3. Use vector database for embeddings and similarity search
|
||||
4. Optimize queries for real-time performance
|
||||
5. Implement proper cleanup for old records
|
||||
|
||||
## Container and Deployment
|
||||
|
||||
1. Use multi-stage Docker builds for optimization
|
||||
2. Support multiple architectures (x86_64, ARM64)
|
||||
3. Use S6 overlay for proper process management
|
||||
4. Implement health checks for all services
|
||||
5. Support hardware passthrough for AI accelerators
|
||||
|
||||
## Integration Rules
|
||||
|
||||
1. **Home Assistant**: Primary integration target
|
||||
2. **MQTT**: Use for real-time communication
|
||||
3. **Hardware**: Support Coral TPU, NVIDIA GPU, Intel hardware acceleration
|
||||
4. **Cameras**: Support RTSP, HTTP streams with go2rtc
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
- Python files: snake_case.py
|
||||
- React components: PascalCase.tsx
|
||||
- Utility files: camelCase.ts
|
||||
- Configuration files: kebab-case.yml
|
||||
- Docker files: Dockerfile.{variant}
|
||||
|
||||
## Git Workflow
|
||||
|
||||
1. Use conventional commit messages
|
||||
2. Create feature branches for new functionality
|
||||
3. Ensure all tests pass before merging
|
||||
4. Use semantic versioning for releases
|
||||
5. Tag releases appropriately
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Python Multiprocessing
|
||||
|
||||
```python
|
||||
# Process-based architecture pattern
|
||||
class SomeProcess(Process):
|
||||
def __init__(self, config, stop_event):
|
||||
self.config = config
|
||||
self.stop_event = stop_event
|
||||
|
||||
def run(self):
|
||||
# Process main loop
|
||||
pass
|
||||
```
|
||||
|
||||
### React Component Pattern
|
||||
|
||||
```tsx
|
||||
interface ComponentProps {
|
||||
// Define props interface
|
||||
}
|
||||
|
||||
const Component = ({ prop1, prop2 }: ComponentProps) => {
|
||||
// Use hooks
|
||||
const [state, setState] = useState();
|
||||
|
||||
// Event handlers with handle prefix
|
||||
const handleClick = () => {
|
||||
// Early return pattern
|
||||
if (!condition) return;
|
||||
|
||||
// Handle event
|
||||
};
|
||||
|
||||
return <div className="tailwind-classes">{/* JSX */}</div>;
|
||||
};
|
||||
```
|
||||
|
||||
### Configuration Pattern
|
||||
|
||||
```python
|
||||
class ConfigModel(FrigateBaseModel):
|
||||
field: str = Field(description="Field description")
|
||||
|
||||
@field_validator('field')
|
||||
def validate_field(cls, v):
|
||||
# Validation logic
|
||||
return v
|
||||
```
|
||||
|
||||
## Build and Package Management
|
||||
|
||||
- Python: Use pip with requirements.txt
|
||||
- Frontend: Use npm/bun with package.json
|
||||
- Container: Multi-stage Docker builds
|
||||
- Development: Use devcontainer for consistent environment
|
||||
|
||||
## This repository prioritizes:
|
||||
|
||||
1. Real-time performance over processing completeness
|
||||
2. Local processing over cloud dependencies
|
||||
3. Home Assistant integration
|
||||
4. Hardware acceleration support
|
||||
5. Extensibility and configuration flexibility
|
||||
Loading…
Reference in New Issue
Block a user