# aasimavichavhan/crowd-sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/aasimavichavhan/crowd-sentinel
- Repository: https://github.com/aasimavichavhan/crowd-sentinel

## Overview

Crowd Sentinel analyzes video for per-zone person density and motion turbulence, combines those signals into risk tiers, forecasts surges, and streams annotated frames and alerts to a command dashboard. The main runtime path is documented in the README and reflected in the sampled streamer, detector, flow, risk, and visualizer code. Dashboard controls and configuration routes are visible in sampled excerpts; exact wiring for some API and stream details is not fully shown.

Main entry points: [`video_streamer.py`](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/video_streamer.py) (Stream Manager), [`main.py`](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/main.py) (FastAPI Service), [`config.py`](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/config.py) (Runtime Configuration), [`static/app.js`](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/static/app.js) (Dashboard Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Video Ingest"]
  node_streamer["Stream Manager<br/>[video_streamer.py]"]
end

subgraph group_analysis["Crowd Analysis"]
  node_detector["Person Detection<br/>[detector.py]"]
  node_flow["Motion Turbulence<br/>[optical_flow.py]"]
  node_risk["Risk Forecasting<br/>[risk_engine.py]"]
  node_visualizer["HUD Overlay<br/>[visualizer.py]"]
  node_config["Runtime Configuration<br/>[config.py]"]
end

subgraph group_service["Streaming Service"]
  node_api["FastAPI Service<br/>[main.py]"]
end

subgraph group_dashboard["Command Dashboard"]
  node_dashboard["Dashboard Client<br/>[app.js]"]
  node_page["Dashboard Page<br/>[index.html]"]
end

node_operator(("Venue Operator"))
node_video(("Video Feed"))
node_yaml["Threshold Settings<br/>[config.yaml]"]
node_videos["Video Library"]
node_field(("Response Teams"))

node_operator -->|"operates"| node_dashboard
node_video -->|"supplies frames"| node_streamer
node_videos -->|"provides clips"| node_streamer
node_api -->|"controls playback"| node_streamer
node_streamer -->|"detects people"| node_detector
node_streamer -->|"measures motion"| node_flow
node_streamer -->|"evaluates zones"| node_risk
node_streamer -->|"renders overlay"| node_visualizer
node_detector -->|"zone counts"| node_risk
node_flow -->|"zone turbulence"| node_risk
node_config -->|"sets detection options"| node_detector
node_config -->|"sets flow options"| node_flow
node_config -->|"sets thresholds"| node_risk
node_yaml -->|"loads settings"| node_config
node_api -->|"updates presets"| node_config
node_streamer -->|"streams frames and telemetry"| node_dashboard
node_page -->|"hosts client"| node_dashboard
node_dashboard -->|"requests controls"| node_api
node_operator -->|"requests dispatch"| node_api
node_api -.->|"reports dispatch intent"| node_field

click node_streamer "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/video_streamer.py"
click node_detector "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/detector.py"
click node_flow "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/optical_flow.py"
click node_risk "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/risk_engine.py"
click node_visualizer "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/visualizer.py"
click node_config "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/config.py"
click node_yaml "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/config.yaml"
click node_api "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/main.py"
click node_dashboard "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/static/app.js"
click node_page "https://github.com/aasimavichavhan/crowd-sentinel/blob/main/static/index.html"
click node_videos "https://github.com/aasimavichavhan/crowd-sentinel/tree/main/sample_videos"

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_streamer toneBlue
class node_detector,node_flow,node_risk,node_visualizer,node_config toneAmber
class node_api toneMint
class node_dashboard,node_page toneRose
class node_operator,node_video,node_field toneIndigo
class node_yaml,node_videos toneTeal
```

## Components

### Video Ingest

- [Stream Manager](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/video_streamer.py): `video_streamer.py`

### Crowd Analysis

- [Person Detection](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/detector.py): `detector.py`
- [Motion Turbulence](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/optical_flow.py): `optical_flow.py`
- [Risk Forecasting](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/risk_engine.py): `risk_engine.py`
- [HUD Overlay](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/visualizer.py): `visualizer.py`
- [Runtime Configuration](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/config.py): `config.py`

### Streaming Service

- [FastAPI Service](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/main.py): `main.py`

### Command Dashboard

- [Dashboard Client](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/static/app.js): `static/app.js`
- [Dashboard Page](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/static/index.html): `static/index.html`

### Other components

- **Venue Operator**
- **Video Feed**
- [Threshold Settings](https://github.com/aasimavichavhan/crowd-sentinel/blob/main/config.yaml): `config.yaml`
- [Video Library](https://github.com/aasimavichavhan/crowd-sentinel/tree/main/sample_videos): `sample_videos`
- **Response Teams**

## Connections

- Venue Operator → Dashboard Client: operates
- Video Feed → Stream Manager: supplies frames
- Video Library → Stream Manager: provides clips
- FastAPI Service → Stream Manager: controls playback
- Stream Manager → Person Detection: detects people
- Stream Manager → Motion Turbulence: measures motion
- Stream Manager → Risk Forecasting: evaluates zones
- Stream Manager → HUD Overlay: renders overlay
- Person Detection → Risk Forecasting: zone counts
- Motion Turbulence → Risk Forecasting: zone turbulence
- Runtime Configuration → Person Detection: sets detection options
- Runtime Configuration → Motion Turbulence: sets flow options
- Runtime Configuration → Risk Forecasting: sets thresholds
- Threshold Settings → Runtime Configuration: loads settings
- FastAPI Service → Runtime Configuration: updates presets
- Stream Manager → Dashboard Client: streams frames and telemetry
- Dashboard Page → Dashboard Client: hosts client
- Dashboard Client → FastAPI Service: requests controls
- Venue Operator → FastAPI Service: requests dispatch
- FastAPI Service → Response Teams: reports dispatch intent