vios-deep-data-notification git:20260603.14e198cA

Immutable. This exact content is served forever at /api/v1/blob/fdd88b2f68e9fb97.

---
description: "Deep reference: VIOS database, notification pub/sub, gRPC, SOAP, Prometheus, and Elasticsearch"
globs: "src/framework/database/**,src/framework/notification/**,src/framework/protocols/**"
alwaysApply: false
---

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Database Layer

## Abstraction (database_manager.h)

- `IDatabaseInterface`: `connect()`, `isConnected()`, `executeQuery()` (raw + parameterized)
- Domain methods for sensors, recordings, users, sessions, events
- `DatabaseConnectionFactory::getInstance()`: `use_centralize_db` -> PostgreSQL (`Postgresql`), else SQLite (`Sqlite`)

## Key Tables (database_schema.h)

| Table | Purpose |
|-------|---------|
| DB_DETAILS | DB version, schema versioning |
| SENSOR_DETAILS | Sensors (credentials, IP, hardware, status) |
| SENSOR_STREAMS | Stream URLs, resolution, encoding, audio |
| VIDEO_RECORD_DETAILS | Recordings (file_path, duration, codec, storage) |
| VIDEO_RECORD_SCHEDULE_DETAILS | Recording schedules |
| EVENTS | Events (start/end time, event_name, video_path) |
| USER_DETAILS | Username, password hash |
| USER_SESSIONS | Session cookies, max age |
| RECORDING_STATUS | Recording state per stream |
| TEMP_VIDEO_FILES | Temp file paths, expiry |

## Connection Management

- **SQLite**: single `sqlite3*` connection, singleton
- **PostgreSQL**: `ConnectionPool` with `queue<shared_ptr<pqxx::connection>>`, `mutex`, `condition_variable`. Pool size: `config.max_centralize_db_conn`. Blocks when empty.
- Transactions: `pqxx::work txn` -> `txn->commit()`
- `QueryBuilder`: `{0}/{1}` placeholders, `escapeString()`, `validateColumnName()` (SQL injection protection)

# Notification Layer

## Broker Selection (NotificationFactory.h)

| Config | Producer | Consumer |
|--------|----------|----------|
| `"redis"` | `NvRedis` (nvds_msgapi) | `RedisSubscriber` |
| `"kafka"` | `NvKafka` (librdkafka, x86_64 only) | `KafkaConsumer` |
| `"mqtt"` | `MqttPublisher` (paho-mqtt) | `MqttSubscriber` |

Typical: Redis for publish, Kafka for consume.

## INotificationInterface (notification_manager.h)

- `sendMessage(Json::Value&)` -- enqueue with `created_at`, messages expire after 1 hour
- `deliverMessage()` -- send to broker
- `processMessageQueue()` -- background thread
- Published from: PeerConnectionManager, sensor_management, sensor_monitoring, sensordatamanager, rtspserver, vst_common

## Protobuf Schemas

- **ds_schema.proto** (3D): Frame(version, id, timestamp, sensorId, objects, fov, rois, segmentation, interactions), Object(id, bbox, type, confidence, bbox3d, pose, gaze, embedding)
- **ds_schema_2d.proto** (2D): simplified Frame(objects only)
- **DsProtoParser**: loads `libnvds_schema_2d.so`/`libnvds_schema_3d.so`, `parseMessage()` binary -> Json::Value

# Protocol Layer

## gRPC (protocols/grpc/viosserver.proto, nvgrpc.h)

- `VstGrpcServer`: `CreateUDPConnection`, `CreateWebrtcConnection`
- `VstGrpcWebRTCSignalingServer`: `sdpExchange`, `iceCandidateExchange` (bidirectional stream)
- Server: `GrpcUdpService`, `GrpcWebrtcSignallingService`
- Client: `GrpcClient` with `VstGrpcServer::NewStub(channel)`
- Gated: `USE_GRPC_SERVER` / `USE_GRPC_CLIENT` (x86_64 only)

## SOAP/ONVIF (protocols/soap/nvsoap.h)

- WS-Discovery: `sendProbe()`, `getProbeResponse()`
- Device: `GetCapabilities`, `GetProfiles`, `GetMediaUri`, `GetReplayUri`, `GetDeviceInformation`, `rebootDevice`
- PTZ: `GetPTZProfiles`, `ContinuousMove`, `Stop`
- Imaging: `getDeviceImageSettings`, `setDeviceImageSettings`
- Profile G (Recording): `GetRecordingSummary`, `FindRecordings`, `GetRecordingSearchResults`

## Prometheus (protocols/prometheus_client/prometheus_client.h)

- Exposer on `config.prometheus_port`
- Gauges: `vms_qos` (metric_name, camera), `vms_metrics` (metric_name, optional camera_name/container_name)
- Metrics: webrtc_fps, recorder_stream_fps, num_active_streams, cpu/ram/gpu_usage, available_storage_mb

## Elasticsearch (protocols/elastic_search/elasticSearch.h)

- URL from `config.video_metadata_server`
- Queries by `sensorId` + `@timestamp`/`timestamp` range
- `getMetadata()` for single-frame, `getBboxPosition()` for batch overlay metadata
- `search_key`: `timestamp` (protobuf) vs `@timestamp` (JSON) based on `use_video_metadata_protobuf`