# eduardovisoni/retail-cctv-analytics architecture

> Architecture diagram of the GitHub repository eduardovisoni/retail-cctv-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eduardovisoni/retail-cctv-analytics
- Repository: https://github.com/eduardovisoni/retail-cctv-analytics

## Overview

1. **System purpose**
   This repository is a small Python client for **live CCTV viewing** from a **Hikvision DVR**, not a full backend or web app. Its current architecture is centered on **consuming RTSP streams**, decoding them with **OpenCV/FFmpeg**, and displaying them locally.

2. **Physical/device boundary**
   The first boundary is hardware: **analog cameras connect by coax to the DVR**, and the **DVR is the only networked device**. The cameras do not have IPs or streams of their own; the DVR acts as the bridge and exposes one RTSP stream per channel.

3. **External stream source**
   The DVR publishes video over RTSP using Hikvision’s channel URL pattern:
   `rtsp://user:pass@dvr-ip:554/Streaming/Channels/<N><MM>`
   where `<N>` selects the camera and `<MM>` selects **main stream** (`01`) or **substream** (`02`). This is the main data input to the software.

4. **Configuration boundary**
   `config.example.py` is the template for local secrets and device settings, while the real `config.py` is excluded from git. That makes credentials and DVR-specific parameters an explicit deployment-time boundary rather than source-controlled application logic.

5. **Runtime stack**
   The application is pure **Python** with **OpenCV** as the media layer. The README notes that `opencv-python` brings its own FFmpeg integration, so there is no separate FFmpeg service in the architecture.

6. **Entry points / user-facing flows**
   There are two main scripts:
   - `test_dvr.py`: a **single-camera diagnostic/viewer**
   - `view_all.py`: a **multi-camera mosaic viewer**
   
   This suggests the repo is organized around two usage paths: validating one stream versus monitoring several streams concurrently.

7. **Stream handling behavior**
   For reliable low-latency viewing, the application forces **RTSP over TCP** through `OPENCV_FFMPEG_CAPTURE_OPTIONS` and sets a very small capture buffer. Architecturally, this is important because it changes the transport from lossy/packet-drop-prone UDP to a more stable stream delivery path.

8. **Concurrency model**
   The multi-camera viewer uses **one thread per camera stream**. That isolates each `VideoCapture.read()` call so a slow or disconnected camera does not block the others. Each thread is responsible for its own reconnect behavior, which makes camera failures local rather than system-wide.

9. **Operational dependency on DVR settings**
   The app is only part of the solution; the DVR must also be configured correctly. Two DVR-side settings are critical to the architecture:
   - **Disable Hik-Connect stream encryption**
   - **Disable H.264+**
   
   Without these, the RTSP session may connect but the video payload will be undecodable by OpenCV/FFmpeg.

10. **Failure modes and diagnostics**
    The README documents several decode errors that all point to the same boundary issue: the stream is either **encrypted**, **corrupted**, or delivered in an unsupported form. The recommended diagnostic path is to test the RTSP URL first with `ffplay` or `ffprobe`; if FFmpeg cannot decode it, the Python code is not the root cause.

11. **Current scope vs. roadmap**
    The repository currently stops at **live visualization**. The README’s roadmap shows planned expansion toward **YOLO-based person detection** and **alerts/counting**, which would likely become a downstream processing layer after frame acquisition.

12. **What to diagram**
    A good architecture diagram for this repo should show:
    - Cameras → DVR → RTSP streams
    - Python/OpenCV client consuming those streams
    - Separate single-camera and multi-camera entry points
    - Config file boundary for credentials/settings
    - DVR-side prerequisites that affect decode success
    - Optional future analytics stage after frame ingestion

Main entry points: [`test_dvr.py`](https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/test_dvr.py) (Single viewer), [`view_all.py`](https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/view_all.py) (Mosaic viewer), [`config.example.py`](https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/config.example.py) (Config template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Device chain"]
  node_cameras(("Cameras<br/>analog sources"))
  node_dvr[("Hikvision DVR<br/>rtsp gateway")]
  node_rtsp_streams["RTSP streams<br/>video input"]
end

subgraph group_runtime["Python client"]
  node_opencv["OpenCV<br/>media runtime"]
  node_ffmpeg["FFmpeg<br/>codec backend"]
  node_transport["TCP capture<br/>rtsp transport"]
  node_test_dvr["Single viewer<br/>diagnostic script<br/>[test_dvr.py]"]
  node_view_all["Mosaic viewer<br/>multi-camera script<br/>[view_all.py]"]
  node_camera_threads["Camera threads<br/>concurrency"]
  node_frame_buffer["Frame buffer<br/>in-memory frames"]
end

subgraph group_ops["Deployment settings"]
  node_config_example["Config template<br/>settings template<br/>[config.example.py]"]
  node_local_config["Local config<br/>secret settings"]
  node_dvr_settings["DVR settings<br/>decode prerequisites"]
  node_diagnostics["ffplay/ffprobe<br/>external tools"]
end

subgraph group_future["Roadmap"]
  node_person_detect{{"Person detection<br/>future analytics"}}
  node_alerts_counting{{"Alerts/counting<br/>future output"}}
end

node_cameras -->|"coax video"| node_dvr
node_dvr -->|"publishes"| node_rtsp_streams
node_config_example -.->|"template"| node_local_config
node_local_config -->|"credentials"| node_test_dvr
node_local_config -->|"credentials"| node_view_all
node_dvr_settings -->|"compatibility"| node_rtsp_streams
node_rtsp_streams -->|"stream delivery"| node_transport
node_transport -->|"capture options"| node_opencv
node_opencv -->|"backend"| node_ffmpeg
node_test_dvr -->|"opens stream"| node_opencv
node_view_all -->|"spawns"| node_camera_threads
node_camera_threads -->|"reads frames"| node_opencv
node_camera_threads -->|"latest frame"| node_frame_buffer
node_test_dvr -.->|"verify stream"| node_diagnostics
node_view_all -.->|"verify stream"| node_diagnostics
node_frame_buffer -.->|"future input"| node_person_detect
node_person_detect -.->|"outputs"| node_alerts_counting

click node_config_example "https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/config.example.py"
click node_test_dvr "https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/test_dvr.py"
click node_view_all "https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/view_all.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cameras,node_dvr,node_rtsp_streams toneBlue
class node_opencv,node_ffmpeg,node_transport,node_test_dvr,node_view_all,node_camera_threads,node_frame_buffer toneAmber
class node_config_example,node_local_config,node_dvr_settings,node_diagnostics toneMint
class node_person_detect,node_alerts_counting toneRose
```

## Components

### Device chain

Physical cameras and DVR boundary

- **Cameras**: analog sources · Coax-connected CCTV cameras with no direct network stream
- **Hikvision DVR**: rtsp gateway · Networked recorder that bridges analog cameras to RTSP channels
- **RTSP streams**: video input · Per-channel main and sub streams exposed by the DVR

### Python client

Live viewing application and media stack

- **OpenCV**: media runtime · Python video capture and decoding layer backed by FFmpeg
- **FFmpeg**: codec backend · Capture backend used through OpenCV for RTSP decoding
- **TCP capture**: rtsp transport · Forces RTSP over TCP and low capture buffering for stability
- [Single viewer](https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/test_dvr.py): diagnostic script · One-camera test path for validating a stream and decode setup · `test_dvr.py`
- [Mosaic viewer](https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/view_all.py): multi-camera script · Multi-stream local viewer that combines several channels · `view_all.py`
- **Camera threads**: concurrency · One thread per stream to isolate blocking reads and reconnects
- **Frame buffer**: in-memory frames · Small capture buffer to keep viewing low-latency

### Deployment settings

Local config and DVR prerequisites

- [Config template](https://github.com/eduardovisoni/retail-cctv-analytics/blob/main/config.example.py): settings template · Example local configuration for credentials and device parameters · `config.example.py`
- **Local config**: secret settings · Gitignored deployment-specific config with DVR credentials and options
- **DVR settings**: decode prerequisites · Disable Hik-Connect encryption and H.264+ for OpenCV/FFmpeg compatibility
- **ffplay/ffprobe**: external tools · FFmpeg-based stream checks used to distinguish stream issues from code issues

### Roadmap

Planned analytics after frame ingestion

- **Person detection**: future analytics · Planned YOLO-based detection stage after frame ingestion
- **Alerts/counting**: future output · Planned downstream analytics for notifications and counting

## Connections

- Cameras → Hikvision DVR: coax video · Analog camera feeds terminate at the DVR
- Hikvision DVR → RTSP streams: publishes · DVR exposes one RTSP stream per channel and quality
- Config template → Local config: template · Example settings are copied into a local deployment config
- Local config → Single viewer: credentials · Single-camera viewer loads local device settings
- Local config → Mosaic viewer: credentials · Multi-camera viewer loads local device settings
- DVR settings → RTSP streams: compatibility · Encryption and H.264+ settings determine whether streams decode
- RTSP streams → TCP capture: stream delivery · RTSP sessions are forced onto TCP for reliability
- TCP capture → OpenCV: capture options · OpenCV receives the RTSP capture configuration
- OpenCV → FFmpeg: backend · OpenCV relies on FFmpeg for RTSP decode
- Single viewer → OpenCV: opens stream · Diagnostic viewer reads a single channel
- Mosaic viewer → Camera threads: spawns · Multi-camera viewer uses one worker thread per stream
- Camera threads → OpenCV: reads frames · Each thread performs its own VideoCapture loop
- Camera threads → Frame buffer: latest frame · Threads update a small buffer for display
- Single viewer → ffplay/ffprobe: verify stream · Recommended when a stream fails to decode
- Mosaic viewer → ffplay/ffprobe: verify stream · Recommended when a stream fails to decode
- Frame buffer → Person detection: future input · Planned analytics would consume captured frames
- Person detection → Alerts/counting: outputs · Detection results may feed alerts and counts
