# danikchernov/sentinel-vision architecture

> Architecture diagram of the GitHub repository danikchernov/sentinel-vision, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danikchernov/sentinel-vision
- Repository: https://github.com/danikchernov/sentinel-vision

## Overview

Sentinel Vision Console is a local-first video intelligence application. A user configures camera, network-stream, or file sources through the dashboard/API; the backend starts per-source workers that ingest frames, detect and track objects, maintain persistent identities, optionally refine labels, and publish previews and summaries. Source definitions persist in a JSON file at runtime. The graph includes the documented optional QLoRA labeling workflow; the excerpts do not show the frontend’s API calls or the training scripts’ internal handoff, so those links are omitted.

Main entry points: [`backend/app/source_manager.py`](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/source_manager.py) (Source manager), [`backend/app/video.py`](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/video.py) (Video source worker), [`backend/app/main.py`](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/main.py) (FastAPI application), [`backend/app/tracker.py`](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/tracker.py) (DeepSORT tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Dashboard and API"]
  node_dashboard["React dashboard<br/>[main.js]"]
  node_api["FastAPI application<br/>[main.py]"]
  node_schemas["API and source schemas<br/>[schemas.py]"]
end

subgraph group_management["Source management"]
  node_manager["Source manager<br/>[source_manager.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_source_store[("Persisted sources")]
  node_runtime["Runtime readiness<br/>[runtime.py]"]
end

subgraph group_perception["Video perception"]
  node_worker["Video source worker<br/>[video.py]"]
  node_detector["YOLO detector<br/>[detector.py]"]
  node_tracker["DeepSORT tracker<br/>[tracker.py]"]
  node_inference["Shared inference stack<br/>[video.py]"]
end

subgraph group_identity["Identity and labeling"]
  node_embedding["Appearance encoder<br/>[embeddings.py]"]
  node_registry[("Identity registry<br/>[identity.py]")]
  node_labeler["Vision labeler<br/>[vlm.py]"]
end

subgraph group_training["Labeler training"]
  node_dataset["Instruction dataset builder"]
  node_trainer["QLoRA trainer<br/>[train_vlm_qlora.py]"]
end

node_operator(("Operator"))
node_feeds(("Video sources"))

node_operator -->|"uses"| node_dashboard
node_api -->|"serves"| node_dashboard
node_api -->|"routes source operations"| node_manager
node_api -->|"reports readiness"| node_runtime
node_api -->|"validates requests"| node_schemas
node_manager -->|"uses source records"| node_schemas
node_manager -->|"uses settings"| node_settings
node_manager -->|"loads and saves"| node_source_store
node_manager -->|"starts workers"| node_worker
node_manager -->|"constructs stack"| node_inference
node_manager -->|"creates registry"| node_registry
node_manager -->|"checks dependencies"| node_runtime
node_feeds -->|"provides video"| node_worker
node_worker -->|"processes frames"| node_inference
node_worker -->|"updates tracks"| node_tracker
node_worker -->|"encodes crops"| node_embedding
node_worker -->|"registers observations"| node_registry
node_worker -->|"labels crops"| node_labeler
node_inference -.->|"runs detection"| node_detector
node_tracker -->|"consumes detections"| node_detector
node_trainer -->|"fine-tunes model"| node_labeler

click node_dashboard "https://github.com/danikchernov/sentinel-vision/blob/master/frontend/src/main.js"
click node_api "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/main.py"
click node_schemas "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/schemas.py"
click node_manager "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/source_manager.py"
click node_settings "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/config.py"
click node_worker "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/video.py"
click node_detector "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/detector.py"
click node_tracker "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/tracker.py"
click node_inference "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/video.py"
click node_embedding "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/embeddings.py"
click node_registry "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/identity.py"
click node_labeler "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/vlm.py"
click node_runtime "https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/runtime.py"
click node_dataset "https://github.com/danikchernov/sentinel-vision/blob/master/train/build_instruction_dataset.py"
click node_trainer "https://github.com/danikchernov/sentinel-vision/blob/master/train/train_vlm_qlora.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_dashboard,node_api,node_schemas toneBlue
class node_manager,node_settings,node_source_store,node_runtime toneAmber
class node_worker,node_detector,node_tracker,node_inference toneMint
class node_embedding,node_registry,node_labeler toneRose
class node_dataset,node_trainer,node_operator,node_feeds toneIndigo
```

## Components

### Dashboard and API

- [React dashboard](https://github.com/danikchernov/sentinel-vision/blob/master/frontend/src/main.js): `frontend/src/main.js`
- [FastAPI application](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/main.py): `backend/app/main.py`
- [API and source schemas](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/schemas.py): `backend/app/schemas.py`

### Source management

- [Source manager](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/source_manager.py): `backend/app/source_manager.py`
- [Runtime settings](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/config.py): `backend/app/config.py`
- **Persisted sources**
- [Runtime readiness](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/runtime.py): `backend/app/runtime.py`

### Video perception

- [Video source worker](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/video.py): `backend/app/video.py`
- [YOLO detector](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/detector.py): `backend/app/detector.py`
- [DeepSORT tracker](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/tracker.py): `backend/app/tracker.py`
- [Shared inference stack](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/video.py): `backend/app/video.py`

### Identity and labeling

- [Appearance encoder](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/embeddings.py): `backend/app/embeddings.py`
- [Identity registry](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/identity.py): `backend/app/identity.py`
- [Vision labeler](https://github.com/danikchernov/sentinel-vision/blob/master/backend/app/vlm.py): `backend/app/vlm.py`

### Labeler training

- [Instruction dataset builder](https://github.com/danikchernov/sentinel-vision/blob/master/train/build_instruction_dataset.py): `train/build_instruction_dataset.py`
- [QLoRA trainer](https://github.com/danikchernov/sentinel-vision/blob/master/train/train_vlm_qlora.py): `train/train_vlm_qlora.py`

### Other components

- **Operator**
- **Video sources**

## Connections

- Operator → React dashboard: uses (evidence: `README.md`)
- FastAPI application → React dashboard: serves (evidence: `backend/app/main.py`)
- FastAPI application → Source manager: routes source operations (evidence: `backend/app/main.py`)
- FastAPI application → Runtime readiness: reports readiness (evidence: `backend/app/main.py`)
- FastAPI application → API and source schemas: validates requests (evidence: `backend/app/main.py`)
- Source manager → API and source schemas: uses source records (evidence: `backend/app/source_manager.py`)
- Source manager → Runtime settings: uses settings (evidence: `backend/app/source_manager.py`)
- Source manager → Persisted sources: loads and saves (evidence: `backend/app/source_manager.py`)
- Source manager → Video source worker: starts workers (evidence: `backend/app/source_manager.py`)
- Source manager → Shared inference stack: constructs stack (evidence: `backend/app/source_manager.py`)
- Source manager → Identity registry: creates registry (evidence: `backend/app/source_manager.py`)
- Source manager → Runtime readiness: checks dependencies (evidence: `backend/app/source_manager.py`)
- Video sources → Video source worker: provides video (evidence: `README.md`)
- Video source worker → Shared inference stack: processes frames (evidence: `backend/app/video.py`)
- Video source worker → DeepSORT tracker: updates tracks (evidence: `backend/app/video.py`)
- Video source worker → Appearance encoder: encodes crops (evidence: `backend/app/video.py`)
- Video source worker → Identity registry: registers observations (evidence: `backend/app/video.py`)
- Video source worker → Vision labeler: labels crops (evidence: `backend/app/video.py`)
- Shared inference stack → YOLO detector: runs detection (evidence: `backend/app/video.py`)
- DeepSORT tracker → YOLO detector: consumes detections (evidence: `backend/app/tracker.py`)
- QLoRA trainer → Vision labeler: fine-tunes model (evidence: `README.md`)
