# mad-dcoder/sentinel-trace architecture

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

- Interactive diagram: https://gitdiagram.com/mad-dcoder/sentinel-trace
- Repository: https://github.com/mad-dcoder/sentinel-trace

## Overview

Sentinel-Trace is an investigator-driven CCTV loss-prevention tool for locating a person in a starting camera window, then following candidates across cameras through human-confirmed search rounds. Its workflow reads only requested video ranges, detects and tracks people, builds appearance embeddings and tracklets, ranks cross-camera matches, and stores case evidence and decisions. The dashboard supports review and report generation; documented capabilities include a learned camera-transition map and forensic DOCX export. Some links reflect README or SOURCE INDEX references because the corresponding implementation excerpts were not shown.

Main entry points: [`pipeline/hunter.py`](https://github.com/mad-dcoder/sentinel-trace/blob/main/pipeline/hunter.py) (On-demand hunt engine), [`config/settings.py`](https://github.com/mad-dcoder/sentinel-trace/blob/main/config/settings.py) (Runtime settings), [`dashboard/app.py`](https://github.com/mad-dcoder/sentinel-trace/blob/main/dashboard/app.py) (Investigation dashboard), [`core/reid.py`](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/reid.py) (Appearance embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_investigation["Investigation workflow"]
  node_dashboard["Investigation dashboard<br/>[app.py]"]
  node_hunter["On-demand hunt engine<br/>[hunter.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_vision["Video and vision"]
  node_video["Video archive<br/>[video.py]"]
  node_motion["Motion sampling<br/>[motion.py]"]
  node_detector["Person detection<br/>[detector.py]"]
  node_tracklet["Tracklet construction<br/>[tracklet.py]"]
  node_attributes["Clothing attributes<br/>[attributes.py]"]
  node_reid["Appearance embeddings<br/>[reid.py]"]
  node_osnet["OSNet-AIN model<br/>[osnet_ain.py]"]
end

subgraph group_matching["Cross-camera matching"]
  node_matcher["Candidate matching<br/>[matcher.py]"]
end

subgraph group_records["Evidence and reporting"]
  node_case_db[("Case evidence store<br/>[database.py]")]
  node_knowledge_db[("Learning and transitions<br/>[database.py]")]
  node_inspector["Route inspection<br/>[inspector.py]"]
  node_report["Forensic report export"]
end

node_investigator(("Investigator"))
node_camera_feeds["CCTV video exports"]

node_investigator -->|"initiates review"| node_dashboard
node_dashboard -->|"starts and guides hunts"| node_hunter
node_hunter -->|"reads requested windows"| node_video
node_camera_feeds -->|"provides recordings"| node_video
node_hunter -->|"checks for motion"| node_motion
node_hunter -->|"detects people"| node_detector
node_hunter -->|"builds person tracks"| node_tracklet
node_hunter -->|"ranks clothing clues"| node_attributes
node_hunter -->|"extracts appearances"| node_reid
node_reid -->|"runs model"| node_osnet
node_hunter -->|"ranks candidates"| node_matcher
node_hunter -->|"stores case evidence"| node_case_db
node_hunter -->|"learns decisions and transitions"| node_knowledge_db
node_dashboard -->|"requests route review"| node_inspector
node_dashboard -->|"generates report"| node_report
node_inspector -->|"reads search evidence"| node_case_db
node_video -->|"loads camera configuration"| node_settings
node_detector -->|"uses model settings"| node_settings
node_motion -->|"uses sampling settings"| node_settings
node_tracklet -->|"uses selection settings"| node_settings
node_reid -->|"loads model settings"| node_settings
node_matcher -->|"uses search settings"| node_settings

click node_dashboard "https://github.com/mad-dcoder/sentinel-trace/blob/main/dashboard/app.py"
click node_hunter "https://github.com/mad-dcoder/sentinel-trace/blob/main/pipeline/hunter.py"
click node_settings "https://github.com/mad-dcoder/sentinel-trace/blob/main/config/settings.py"
click node_video "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/video.py"
click node_motion "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/motion.py"
click node_detector "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/detector.py"
click node_tracklet "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/tracklet.py"
click node_attributes "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/attributes.py"
click node_reid "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/reid.py"
click node_osnet "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/models/osnet_ain.py"
click node_matcher "https://github.com/mad-dcoder/sentinel-trace/blob/main/core/matcher.py"
click node_case_db "https://github.com/mad-dcoder/sentinel-trace/blob/main/db/database.py"
click node_knowledge_db "https://github.com/mad-dcoder/sentinel-trace/blob/main/db/database.py"
click node_inspector "https://github.com/mad-dcoder/sentinel-trace/blob/main/utils/inspector.py"
click node_report "https://github.com/mad-dcoder/sentinel-trace/blob/main/utils/report_generator.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_hunter,node_settings toneBlue
class node_video,node_motion,node_detector,node_tracklet,node_attributes,node_reid,node_osnet toneAmber
class node_matcher toneMint
class node_case_db,node_knowledge_db,node_inspector,node_report toneRose
class node_investigator,node_camera_feeds toneIndigo
```

## Components

### Investigation workflow

- [Investigation dashboard](https://github.com/mad-dcoder/sentinel-trace/blob/main/dashboard/app.py): `dashboard/app.py`
- [On-demand hunt engine](https://github.com/mad-dcoder/sentinel-trace/blob/main/pipeline/hunter.py): `pipeline/hunter.py`
- [Runtime settings](https://github.com/mad-dcoder/sentinel-trace/blob/main/config/settings.py): `config/settings.py`

### Video and vision

- [Video archive](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/video.py): `core/video.py`
- [Motion sampling](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/motion.py): `core/motion.py`
- [Person detection](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/detector.py): `core/detector.py`
- [Tracklet construction](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/tracklet.py): `core/tracklet.py`
- [Clothing attributes](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/attributes.py): `core/attributes.py`
- [Appearance embeddings](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/reid.py): `core/reid.py`
- [OSNet-AIN model](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/models/osnet_ain.py): `core/models/osnet_ain.py`

### Cross-camera matching

- [Candidate matching](https://github.com/mad-dcoder/sentinel-trace/blob/main/core/matcher.py): `core/matcher.py`

### Evidence and reporting

- [Case evidence store](https://github.com/mad-dcoder/sentinel-trace/blob/main/db/database.py): `db/database.py`
- [Learning and transitions](https://github.com/mad-dcoder/sentinel-trace/blob/main/db/database.py): `db/database.py`
- [Route inspection](https://github.com/mad-dcoder/sentinel-trace/blob/main/utils/inspector.py): `utils/inspector.py`
- [Forensic report export](https://github.com/mad-dcoder/sentinel-trace/blob/main/utils/report_generator.py): `utils/report_generator.py`

### Other components

- **Investigator**
- **CCTV video exports**

## Connections

- Investigator → Investigation dashboard: initiates review (evidence: `README.md`)
- Investigation dashboard → On-demand hunt engine: starts and guides hunts (evidence: `dashboard/app.py`)
- On-demand hunt engine → Video archive: reads requested windows (evidence: `pipeline/hunter.py`)
- CCTV video exports → Video archive: provides recordings (evidence: `README.md`)
- On-demand hunt engine → Motion sampling: checks for motion (evidence: `pipeline/hunter.py`)
- On-demand hunt engine → Person detection: detects people (evidence: `pipeline/hunter.py`)
- On-demand hunt engine → Tracklet construction: builds person tracks (evidence: `pipeline/hunter.py`)
- On-demand hunt engine → Clothing attributes: ranks clothing clues (evidence: `pipeline/hunter.py`)
- On-demand hunt engine → Appearance embeddings: extracts appearances (evidence: `pipeline/hunter.py`)
- Appearance embeddings → OSNet-AIN model: runs model (evidence: `core/reid.py`)
- On-demand hunt engine → Candidate matching: ranks candidates (evidence: `pipeline/hunter.py`)
- On-demand hunt engine → Case evidence store: stores case evidence (evidence: `pipeline/hunter.py`)
- On-demand hunt engine → Learning and transitions: learns decisions and transitions (evidence: `pipeline/hunter.py`)
- Investigation dashboard → Route inspection: requests route review (evidence: `dashboard/app.py`)
- Investigation dashboard → Forensic report export: generates report (evidence: `dashboard/app.py`)
- Route inspection → Case evidence store: reads search evidence (evidence: `utils/inspector.py`)
- Video archive → Runtime settings: loads camera configuration (evidence: `core/video.py`)
- Person detection → Runtime settings: uses model settings (evidence: `core/detector.py`)
- Motion sampling → Runtime settings: uses sampling settings (evidence: `core/motion.py`)
- Tracklet construction → Runtime settings: uses selection settings (evidence: `core/tracklet.py`)
- Appearance embeddings → Runtime settings: loads model settings (evidence: `core/reid.py`)
- Candidate matching → Runtime settings: uses search settings (evidence: `core/matcher.py`)