# yuragb/c-_camera_yolo_service architecture

> Architecture diagram of the GitHub repository yuragb/c-_camera_yolo_service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yuragb/c-_camera_yolo_service
- Repository: https://github.com/yuragb/c-_camera_yolo_service

## Overview

#### Purpose and Entry Point
`Camera CV Service` is a C++17 edge video service: capture camera/file frames, run YOLO detection, and deliver low-latency H.264 WebRTC video plus detection/metrics metadata. The process entry point is `src/main.cpp`; CMake builds the native executable via `CMakeLists.txt`.

#### Runtime Composition
Startup loads environment-driven pipeline settings, selects platform services, capture input, inference backend, and WebRTC signaling/media services. Runtime configuration is centralized in `include/core/pipeline/runtime_config.h` and `src/core/pipeline/runtime_config.cpp`. OS-dependent defaults, paths, and camera enumeration are isolated behind `include/platform/platform_services.h`, with implementations in `src/platform/windows/windows_platform_services.cpp` and `src/platform/linux/linux_platform_services.cpp`.

#### Capture and Frame Ownership
`CameraManager` manages one or more sources and provides the pipeline’s current frames. Capture is abstracted by `include/capture/video_source.h`; the concrete OpenCV source supports cameras and video files in `src/capture/opencv_video_source.cpp`. Shared frame representation belongs in `include/models/frame.h`. This is the boundary between device/file I/O and all downstream processing.

#### Decoupled Video and Detection Flows
The architecture intentionally separates:
- **Live path:** latest capture frame → resize/encode → WebRTC media. Stale frames are dropped to cap latency.
- **Detection path:** captured frames → asynchronous inference → tracking → DataChannel JSON. It may lag and must not block video.
- **Telemetry:** video latency samples and interval metrics are generated independently of inference and sent through the DataChannel.

Pipeline coordination is rooted in `src/camera_manager.cpp`, `src/inference_engine.cpp`, and `src/webrtc_service_media.cpp`. Object tracking is a distinct post-inference stage in `src/tracking_manager.cpp`, backed by vendored `third_party/ByteTrack-cpp`.

#### Inference Boundary and Acceleration
`InferenceEngine` owns model execution and detection processing through a backend interface in `include/inference_backend.h`. `src/inference_backend_factory.cpp` chooses:
- ONNX Runtime implementation: `src/onnx_runtime_backend.cpp`
- optional TensorRT implementation: `src/tensorrt_runtime_backend.cpp`

TensorRT is compile-time gated and falls back to ONNX Runtime if unavailable. Models are external runtime assets under `models/` or mounted paths, not repository contents.

#### WebRTC, Encoding, and Signaling
`WebRTCService` integrates libdatachannel peer connections, an H.264 media track (`liveStream`), and DataChannel (`detectionStream`). Responsibilities are split across `src/webrtc_service.cpp`, `src/webrtc_service_peer.cpp`, `src/webrtc_service_media.cpp`, and `src/webrtc_service_signaling.cpp`. Signaling uses an external WebSocket server for registration, SDP offers/answers, and ICE exchange; default STUN is Google’s public server. Optional HS256 JWT authentication uses OpenSSL and a shared signaling-server secret.

H.264 encoding is wrapped by `include/openh264_encoder.h` and `src/openh264_encoder.cpp`; OpenH264 is dynamically loaded at runtime.

#### Deployment Boundaries
The primary runtime is native Windows/Linux or Linux containers. `Dockerfile` provides the CPU image; `Dockerfile.tensorrt` and `docker-compose.tensorrt.yml` support NVIDIA TensorRT. Kubernetes/k3s deployment manifests are in `k3s/05-yolo-service-deployment.yaml`, with ConfigMap and Secret separation in `k3s/02-yolo-service-configmap.yaml` and `k3s/02-yolo-service-secret.yaml`. Cameras, models, media, GPU devices, and signaling remain external infrastructure dependencies.

Main entry points: [`src/main.cpp`](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/main.cpp) (Process entry), [`src/camera_manager.cpp`](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/camera_manager.cpp) (Camera manager), [`src/webrtc_service.cpp`](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/webrtc_service.cpp) (WebRTC service), [`src/inference_engine.cpp`](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/inference_engine.cpp) (Inference engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Native service"]
  node_build["CMake build<br/>[CMakeLists.txt]"]
  node_entry["Process entry<br/>C++ entrypoint<br/>[main.cpp]"]
  node_runtime_config["Runtime configuration<br/>pipeline settings<br/>[runtime_config.cpp]"]
  node_platform["Platform services<br/>OS abstraction"]
  node_camera_manager["Camera manager<br/>pipeline coordinator<br/>[camera_manager.cpp]"]
  node_video_source["OpenCV video source<br/>capture adapter"]
  node_frame["Shared frame<br/>frame model<br/>[frame.h]"]
  node_inference["Inference engine<br/>async detection"]
  node_backend_factory["Backend factory<br/>backend selection"]
  node_onnx["ONNX Runtime backend<br/>inference backend"]
  node_tensorrt["TensorRT backend<br/>optional inference backend"]
  node_tracking["Tracking manager<br/>post-inference tracking"]
  node_encoder["OpenH264 encoder<br/>H.264 encoder"]
  node_webrtc_media["WebRTC media path<br/>low-latency video"]
  node_webrtc_service["WebRTC service<br/>peer and DataChannel service<br/>[webrtc_service.cpp]"]
  node_signaling["Signaling integration<br/>WebSocket signaling"]
end

subgraph group_external["External dependencies"]
  node_camera_input(("Camera or video file<br/>capture input"))
  node_models["YOLO model assets<br/>runtime model"]
  node_signaling_server["Signaling server<br/>external WebSocket service"]
end

subgraph group_deployment["Deployment"]
  node_deployment_assets["Container and k3s deployment<br/>deployment assets"]
end

node_build -->|"builds"| node_entry
node_entry -->|"loads"| node_runtime_config
node_entry -->|"selects"| node_platform
node_entry -->|"starts"| node_camera_manager
node_entry -->|"starts"| node_inference
node_entry -->|"starts"| node_webrtc_service
node_runtime_config -->|"configures"| node_camera_manager
node_platform -->|"enumerates cameras"| node_camera_manager
node_camera_input -->|"frames"| node_video_source
node_video_source -->|"captures"| node_camera_manager
node_camera_manager -->|"publishes current frame"| node_frame
node_frame -->|"latest-frame live path"| node_webrtc_media
node_webrtc_media -->|"encodes"| node_encoder
node_encoder -->|"H.264 liveStream"| node_webrtc_service
node_frame -->|"asynchronous detection path"| node_inference
node_inference -->|"uses"| node_backend_factory
node_backend_factory -->|"default backend"| node_onnx
node_backend_factory -.->|"optional backend"| node_tensorrt
node_models -->|"model"| node_onnx
node_models -->|"model"| node_tensorrt
node_inference -->|"detections"| node_tracking
node_tracking -->|"DataChannel JSON"| node_webrtc_service
node_webrtc_media -->|"latency metrics"| node_webrtc_service
node_webrtc_service -->|"negotiates peers"| node_signaling
node_signaling -->|"WebSocket"| node_signaling_server
node_deployment_assets -.->|"deploys"| node_entry

click node_build "https://github.com/yuragb/c-_camera_yolo_service/blob/master/CMakeLists.txt"
click node_entry "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/main.cpp"
click node_runtime_config "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/core/pipeline/runtime_config.cpp"
click node_platform "https://github.com/yuragb/c-_camera_yolo_service/blob/master/include/platform/platform_services.h"
click node_camera_manager "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/camera_manager.cpp"
click node_video_source "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/capture/opencv_video_source.cpp"
click node_frame "https://github.com/yuragb/c-_camera_yolo_service/blob/master/include/models/frame.h"
click node_inference "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/inference_engine.cpp"
click node_backend_factory "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/inference_backend_factory.cpp"
click node_onnx "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/onnx_runtime_backend.cpp"
click node_tensorrt "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/tensorrt_runtime_backend.cpp"
click node_tracking "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/tracking_manager.cpp"
click node_encoder "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/openh264_encoder.cpp"
click node_webrtc_media "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/webrtc_service_media.cpp"
click node_webrtc_service "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/webrtc_service.cpp"
click node_signaling "https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/webrtc_service_signaling.cpp"
click node_deployment_assets "https://github.com/yuragb/c-_camera_yolo_service/blob/master/Dockerfile"

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_build,node_entry,node_runtime_config,node_platform,node_camera_manager,node_video_source,node_frame,node_inference,node_backend_factory,node_onnx,node_tensorrt,node_tracking,node_encoder,node_webrtc_media,node_webrtc_service,node_signaling toneBlue
class node_camera_input,node_models,node_signaling_server toneAmber
class node_deployment_assets toneMint
```

## Components

### Native service

C++ edge video runtime.

- [CMake build](https://github.com/yuragb/c-_camera_yolo_service/blob/master/CMakeLists.txt): build · `CMakeLists.txt`
- [Process entry](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/main.cpp): C++ entrypoint · `src/main.cpp`
- [Runtime configuration](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/core/pipeline/runtime_config.cpp): pipeline settings · Loads environment-driven pipeline settings. · `src/core/pipeline/runtime_config.cpp`
- [Platform services](https://github.com/yuragb/c-_camera_yolo_service/blob/master/include/platform/platform_services.h): OS abstraction · Provides OS defaults, paths, and camera enumeration. · `include/platform/platform_services.h`
- [Camera manager](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/camera_manager.cpp): pipeline coordinator · Owns sources and exposes current frames. · `src/camera_manager.cpp`
- [OpenCV video source](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/capture/opencv_video_source.cpp): capture adapter · Captures camera or file input. · `src/capture/opencv_video_source.cpp`
- [Shared frame](https://github.com/yuragb/c-_camera_yolo_service/blob/master/include/models/frame.h): frame model · `include/models/frame.h`
- [Inference engine](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/inference_engine.cpp): async detection · Runs detection without blocking live video. · `src/inference_engine.cpp`
- [Backend factory](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/inference_backend_factory.cpp): backend selection · Selects TensorRT when compiled and available, otherwise ONNX Runtime. · `src/inference_backend_factory.cpp`
- [ONNX Runtime backend](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/onnx_runtime_backend.cpp): inference backend · `src/onnx_runtime_backend.cpp`
- [TensorRT backend](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/tensorrt_runtime_backend.cpp): optional inference backend · Compile-time-gated accelerator backend. · `src/tensorrt_runtime_backend.cpp`
- [Tracking manager](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/tracking_manager.cpp): post-inference tracking · Associates detections using vendored ByteTrack. · `src/tracking_manager.cpp`
- [OpenH264 encoder](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/openh264_encoder.cpp): H.264 encoder · Dynamically loads OpenH264 at runtime. · `src/openh264_encoder.cpp`
- [WebRTC media path](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/webrtc_service_media.cpp): low-latency video · Resizes and encodes latest frames; stale frames are dropped. · `src/webrtc_service_media.cpp`
- [WebRTC service](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/webrtc_service.cpp): peer and DataChannel service · Publishes liveStream video and detectionStream metadata. · `src/webrtc_service.cpp`
- [Signaling integration](https://github.com/yuragb/c-_camera_yolo_service/blob/master/src/webrtc_service_signaling.cpp): WebSocket signaling · Handles registration, SDP, ICE, and optional JWT authentication. · `src/webrtc_service_signaling.cpp`

### External dependencies

Infrastructure and runtime-provided assets.

- **Camera or video file**: capture input
- **YOLO model assets**: runtime model · Mounted or externally supplied model files.
- **Signaling server**: external WebSocket service · Provides peer negotiation and authentication secret boundary.

### Deployment

Supported packaging and orchestration.

- [Container and k3s deployment](https://github.com/yuragb/c-_camera_yolo_service/blob/master/Dockerfile): deployment assets · CPU and TensorRT images with ConfigMap and Secret deployment configuration. · `Dockerfile`

## Connections

- CMake build → Process entry: builds
- Process entry → Runtime configuration: loads
- Process entry → Platform services: selects
- Process entry → Camera manager: starts
- Process entry → Inference engine: starts
- Process entry → WebRTC service: starts
- Runtime configuration → Camera manager: configures
- Platform services → Camera manager: enumerates cameras
- Camera or video file → OpenCV video source: frames
- OpenCV video source → Camera manager: captures
- Camera manager → Shared frame: publishes current frame
- Shared frame → WebRTC media path: latest-frame live path
- WebRTC media path → OpenH264 encoder: encodes
- OpenH264 encoder → WebRTC service: H.264 liveStream
- Shared frame → Inference engine: asynchronous detection path
- Inference engine → Backend factory: uses
- Backend factory → ONNX Runtime backend: default backend
- Backend factory → TensorRT backend: optional backend
- YOLO model assets → ONNX Runtime backend: model
- YOLO model assets → TensorRT backend: model
- Inference engine → Tracking manager: detections
- Tracking manager → WebRTC service: DataChannel JSON
- WebRTC media path → WebRTC service: latency metrics
- WebRTC service → Signaling integration: negotiates peers
- Signaling integration → Signaling server: WebSocket
- Container and k3s deployment → Process entry: deploys