Skip to content

System Architecture

VibeNVR is designed as a modern, modular microservices ecosystem to ensure reliability, security, and high performance.

🏗️ Core Components

VibeNVR is split into four primary services, each running in its own Docker container:

1. Frontend (React SPA)

A premium, responsive dashboard built with React, Vite, and TailwindCSS. It communicates with the backend via a REST API and handles low-latency video playback using the WebCodecs API.

2. Backend (FastAPI)

The central logic hub powered by FastAPI (Python). - Authentication: Full JWT stack with 2FA support. - API: Handles configuration, user management, and event queries. - Media Relay: Manages secure, authenticated access to video streams via HttpOnly cookies.

3. VibeEngine (Custom Python Engine)

The dedicated video processing service. This is the "heavy lifter" of the system: - Stream Ingestion: Uses PyAV (native FFmpeg bindings) for robust RTSP connection management and packet demuxing. Optionally routes connections through an internal go2rtc Gateway (127.0.0.1:8554) to stabilize flaky consumer IP cameras and prevent IP bans. - Image Processing: Leverages OpenCV (cv2) for motion detection analysis, text overlays, and dynamic JPEG encoding for legacy previews. - Modular Design: The engine core is highly modularized (stream_reader, motion_detector, recording_manager, mask_handler, overlay_handler) for maximum stability. - Security: Communicates via internal Docker networks and requires a shared WEBHOOK_SECRET for backend interaction. - Decoupled Detection: Supports both server-side pixel analysis (OpenCV) and hardware-side edge event handling (ONVIF PullPoint). The detection engine is logically decoupled from the activation schedule (Always, Scheduled, Manual), allowing for hybrid configurations.

4. Database (PostgreSQL / SQLite)

Uses PostgreSQL 15 by default for reliable storage of all persistent data, including camera configurations, user settings, and the event timeline. Alternatively, the backend fully supports SQLite via a direct file path (e.g. sqlite:////data/vibe.db) for lightweight edge deployments, automatically configuring Write-Ahead Logging (WAL) for concurrency.

5. Telemetry Worker (Cloudflare Edge)

A highly modularized Cloudflare Worker repository (vibenvr-telemetry-worker) that handles global telemetry, metadata ingestion, and secure dashboarding. - Modularity: Split securely into dedicated ES modules (security.js, api.js, assets.js, etc.) to stay well below the 1000 LOC limits. - Edge Security: Provides native strict Content-Security-Policy (CSP) headers and input sanitization at the CDN edge before requests reach the VibeNVR origin.

🔒 Security Model

VibeNVR implements a "Security by Design" approach: - Internal API Protection: Sensitive internal APIs (like the Engine's control port) are not exposed to the host machine. - Token Scoping: API tokens can be created with specific TTLs and limited permissions. - Reverse Proxy Ready: Built to work seamlessly behind Nginx Proxy Manager or Traefik with full WebSocket support.

🧼 Development Hygiene & Build Isolation

VibeNVR enforces strict isolation between development artifacts and production assets: - Build Hygiene: Every Docker context is isolated via rigorous .dockerignore files, ensuring no venv, __pycache__, or node_modules leak into the ultra-lean (~1GB) production images. - Repository Integrity: The project uses recursive .gitignore policies to ensure all local management scripts and temporary artifacts remain local-only and are never tracked by Git. - Automated Assurance: Every build is verified against a custom security and hygiene auditor to maintain these standards.

⚡ Performance Optimization

  • Passthrough Recording: Optionally records raw RTSP streams directly to disk without re-encoding, resulting in near-zero CPU usage.
  • OS-level I/O Buffering: Deprecated the use of flush_packets=0 in the PyAV muxer to prevent severe RAM bloat during prolonged recording sessions. Storage optimization now relies on native OS-level disk buffering (e.g., ZFS ZIL/ARC) without forcefully halting FFmpeg packet flushes.
  • MP4 Metadata Placement: Passthrough recordings are explicitly saved as standard MP4s with the +faststart flag. This forces the moov atom to the beginning of the file upon completion, guaranteeing instant playback and precise frame seeking in all Chromium and Firefox browsers without the playback/seek issues associated with fragmented MP4s.
  • Dual-Stream Handling: The Engine initializes independent StreamReader instances for main and sub-streams. Sub-streams are prioritized for UI frame generation to reduce client-side bandwidth and CPU overhead in grid views.
  • Fallback Logic: If a sub-stream is not configured (optional), the Engine automatically falls back to the main stream reader for all operations, including live UI frames.
  • Adaptive Streaming: Automatically switches between high-performance WebCodecs (H.264), MSE (Media Source Extensions), optimized Sub-Streams, and compatible JPEG polling fallback.
  • Live Audio: Implements low-latency audio streaming using browser WebCodecs (PCM ALAW/ULAW). The Engine performs secure authentication and direct passthrough of G.711 streams to the client, minimizing backend CPU overhead and ensuring perfect AV synchronization.
  • Database Query Optimization: Critical API endpoints (such as get_users) employ eager loading techniques (selectinload) to resolve N+1 query issues during serialization. Background services (such as the health monitor) use lightweight queries (get_active_cameras_lightweight) to prevent memory exhaustion (OOM) and excessive database I/O. Furthermore, aggregations for historical statistics (e.g. get_stats_history) are performed directly at the database level to prevent application-side memory bloat.