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.
  • 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, ensuring scalable performance from O(N) to O(1).