OpenNVR relies on a structurally decoupled, microservice-based architecture explicitly engineered to maximize security, eliminate vendor lock-in, and guarantee absolute data sovereignty. By isolating the data layer, the continuous recording mechanism, and the AI inference engine, the system achieves unprecedented stability and flexibility.

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, ensuring your main NVR absolutely never crashes due to heavy GPU tensor workloads.