OpenNVR

Core Architecture

OpenNVR uses a decoupled, microservice-based architecture built to harden security, avoid vendor lock-in, and keep data sovereignty with the operator. Isolating the data layer, the continuous-recording engine, and the AI inference layer from each other is what gives the system its stability and flexibility — a fault in one doesn’t take down the others.

The core platform consists of three primary logical blocks, all operating as independently containerized environments.

1. The Data Layer (PostgreSQL)

At the foundation of OpenNVR sits the persistence and state layer. Rather than relying on fragile, file-based SQLite databases or proprietary binary blobs like traditional NVRs, OpenNVR utilizes an enterprise-grade relational database running natively via Docker Compose.

  • PostgreSQL Engine: Handles millions of rows of complex metadata instantly.
  • Object Relational Mapping: We rely on robust SQLAlchemy integrations to manage schema migrations cleanly and programmatically via Alembic.
  • Encrypted Storage State: The data layer stores critical BYOK (Bring Your Own Key) cryptographic salts, user profiles, hardware MFA seeds, retention rules, and precise audit trails.

[!TIP] The database connection is explicitly managed internally by the FastAPI backend via the DATABASE_URL environment variable found in server/env.example.

2. The Recording Layer (MediaMTX + Core APIs)

This layer is the beating heart of the surveillance system, responsible for natively consuming and retaining video streams at ultra-low latencies.

  • RTSP & WebRTC Engine: We leverage the incredible open-source power of MediaMTX. MediaMTX acts as the robust proxy layer capable of simultaneously digesting thousands of inbound RTSP feeds and rebroadcasting them out via WebRTC and HLS protocols.
  • Dynamic API Control: Rather than manually editing mediamtx.yml configuration files, OpenNVR’s FastAPI backend dynamically pushes configurations directly into the media server’s memory. When you add a camera on the UI, the Python backend instantly establishes the RTSP tunnels automatically.

3. Web Application & AI Orchestration

The final layer handles orchestration, user interface rendering, and routing data towards the external AI ecosystem.

  • Vite/React Frontend (app/): A hyper-fast, state-of-the-art interactive dashboard. By fetching WebRTC signaling data directly from the FastAPI backend, the React components render live arrays of multi-megapixel cameras with virtually zero latency.
  • FastAPI Backend (server/): The central nervous system. It processes all REST API commands, manages WebSockets for live Suricata alerts, handles strict JWT authentication, and acts as the gatekeeper for the database.
  • Stateless AI Adapters: External inferencing models (like kai-c or HuggingFace cloud endpoints) exist entirely outside of this core architecture. The backend merely “routes” frames to them using an HTTP API, so your main NVR never goes down because of a heavy GPU tensor workload.

AI Adapter Design Patterns

To let the AI Adapter repository scale to hundreds of community-contributed models without suffering from bloat, the sub-architecture strictly uses three robust Gang of Four design patterns:

  1. The Strategy Pattern (Core Router): Tasks are blindly routed by the ModelRouter based on configuration, treating complex ML algorithms as perfectly interchangeable strategies at runtime.
  2. The Adapter Pattern (Base Interface): The BaseAdapter interface strictly bridges incompatible ML frameworks (PyTorch vs ONNX vs Transformers) into simple JSON execution contracts so the FastAPI server never breaks.
  3. The Abstract Factory Pattern (Lazy Registry): The configuration file acts as an Abstract Factory on boot. Even with 500 models available in the repository, the Factory will only instantiate the classes explicitly enabled, so unused models consume no memory.