# atharvk-28/amd-slingshot architecture

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

- Interactive diagram: https://gitdiagram.com/atharvk-28/amd-slingshot
- Repository: https://github.com/atharvk-28/amd-slingshot

## Overview

##### What this project is (type + purpose)
**CrowdSense AI** is a **full-stack, real-time “computer vision → risk scoring → decision support dashboard” system**.

- **Frontend**: React 18 (Vite) command-center UI that visualizes live telemetry (CPI, surge, chaos, routing) and likely renders dashboards and alerts.
- **Backend**: Python **FastAPI** “edge node” that runs the computer vision pipeline (OpenCV + Ultralytics YOLOv8), computes the risk metrics (CPI, ΔCPI, chaos multiplier), and **streams processed outputs over WebSockets** (JSON data and possibly video).

Architecturally, this is a **real-time streaming system** (not a request/response CRUD app): the important flows are continuous frames → inference → metrics → streaming → UI.

##### Read the repository structure as architecture hints
From the tree:

##### Top-level
- `CMADS_App/frontend/` and `CMADS_App/backend/` clearly indicate a **two-tier** system with a realtime channel between them.
- `README.md` explicitly confirms: *React command center* + *FastAPI WebSocket backend*.
- Deployment hints:
- `frontend/vercel.json` → frontend deploy target is Vercel.
- README mentions backend on Render.

##### Backend
- `backend/main.py` → likely contains:
- FastAPI app initialization
- WebSocket endpoint (e.g., `/ws`)
- CV pipeline loop and serialization to JSON

##### Frontend
- `frontend/src/pages/*` indicates UI “screens”:
- `Dashboard.tsx` → main telemetry view (charts, alerts)
- `Login.tsx` → implies auth might exist or is planned (include as optional/placeholder if it’s not wired end-to-end)
- `Picker.tsx` → might select camera feed / scenario / venue
- `Recharts` mentioned in README → indicates the dashboard consumes time-series metrics.
- `.env.example` and README variable `VITE_WS_URL` → **explicit dependency**: frontend must know the backend WebSocket URL.

##### Client-side (Browser)
- **Operator / Public Safety Authority** (human actor)
- **React Command Center (Vite app)**
- Pages: Dashboard, Architecture, Login, Picker
- Live telemetry charts (Recharts)
- Alert UI state (SURGE WARNING, Red Choke Point)
- Route visualization (A* output)

##### Backend (Edge Node / Server)
- **FastAPI App**
- WebSocket endpoint `/ws` (as per README env var)
- Any REST endpoints if present (unknown from tree; keep optional)
- **Vision Pipeline Module (conceptual even if in one file)**
- Video input capture (camera / file / RTSP—represent generically as “Video Source”)
- Preprocessing (OpenCV; canny/edges, frame differencing)
- **YOLOv8 inference** (Ultralytics + PyTorch)
- Optical Flow (Lucas-Kanade grid flow)
- **Risk/Decision Engine**
- CPI computation
- ΔCPI surge detection (rolling memory queue, 3-second threshold)
- Chaos Multiplier (std dev of movement angles)
- Choke point classification (“Red Zone”)
- **Routing Engine**
- A* pathfinding recomputation
- Output: recommended safe route(s)

##### External / Infrastructure
- **Video Source** (CCTV camera, drone feed, recorded video)
- **Deployment**
- Vercel hosting the frontend
- Render hosting the backend
- **Hardware Acceleration (AMD EPYC / ROCm)**

##### Frontend → Backend (WebSocket)
Even if not implemented, it’s a typical WebSocket bi-directional pattern; include if it matches your UI (Picker suggests it might).

##### Optional / “to confirm”
- **Login/Auth**:
- If `Login.tsx` is only UI, show it as “UI placeholder”.
- If auth exists (not visible here), add Auth Provider + token validation in backend.

##### Architectural patterns to emphasize (specific to this repo)
- **Edge-first processing**: inference and CV run on the backend close to the camera feed; only derived telemetry is streamed outward.
- **Streaming/event-driven UI**: WebSocket-driven updates powering charts and alerts.

**Context (Level 1)**
- Actor: Safety Operator
- System: CrowdSense AI
- External: CCTV/Camera Feed
- Hosting: Vercel (UI), Render/Edge Server (backend)

**Container (Level 2)**
- Browser: React App (Dashboard/Login/Picker)
- Backend: FastAPI App
- Link: WebSocket `/ws`
- Input: Video Source
- Compute: AMD ROCm acceleration under inference

**Dynamic (Sequence)**
##### Frontend updates charts + warnings + route overlay

Before finalizing, quickly open:
- `backend/main.py`:
- exact WebSocket path (`/ws` per README, confirm)
- whether backend also serves video frames or only JSON
- whether it ingests from webcam/rtsp/file
- message schema fields
- `frontend/src/pages/Dashboard.tsx` and `Picker.tsx`:
- confirm whether frontend sends messages to backend (bi-directional WS)
- `frontend/.env.example`:
- confirm env var names (likely `VITE_WS_URL`)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =======================
%% Level 1: Context
%% =======================
subgraph L1["C4 - Level 1: Context (CrowdSense AI)"]
direction TB

Operator["Safety Operator / Public Safety Authority"]:::external

subgraph L1SYS["CrowdSense AI System"]
direction TB
System["CrowdSense AI\nReal-time CV → Risk Scoring → Decision Support"]:::system
end

Camera["Video Source\n(CCTV / Drone / Recorded Feed)"]:::external
Vercel["Vercel\n(Frontend Hosting)"]:::external
Render["Render / Edge Server\n(Backend Hosting)"]:::external

Operator -->|"uses"| System
Camera -->|"provides video stream"| System
Vercel -->|"hosts"| System
Render -->|"hosts"| System
end

%% =======================
%% Level 2: Containers
%% =======================
subgraph L2["C4 - Level 2: Containers (Runtime Architecture)"]
direction TB

subgraph UL["User Lane"]
direction TB
U1["Safety Operator"]:::external
end

subgraph CL["Client Lane (Browser + Vercel)"]
direction TB
V1["Vercel (Static Hosting)"]:::external
B1["Browser (React 18)"]:::frontend

subgraph RCC["React Command Center (Vite)"]
direction TB
FEEntry["React Entry (React 18 mount)\nmain.tsx"]:::frontend
FEShell["App Shell + Routing\nApp.tsx"]:::frontend

subgraph UIP["UI Pages"]
direction TB
PageDash["Dashboard\n(React + Recharts Telemetry + Alerts + Route UI)"]:::frontend
PagePick["Picker\n(Camera/Scenario Selection)"]:::frontend
PageArch["Architecture\n(Docs/Explanation UI)"]:::frontend
PageLogin["Login\n(Auth UI placeholder)"]:::frontend
end

FEEnv["WebSocket URL Config\nVITE_WS_URL (.env)"]:::config
FEPkg["Frontend Dependencies\n(React/Vite/Recharts/etc.)"]:::config
FEDeploy["Vercel Config"]:::config
end
end

subgraph NL["Network Lane"]
direction TB
WS["WebSocket (wss)\nEndpoint: /ws"]:::network
end

subgraph BL["Backend Lane (Render / Edge Node)"]
direction TB
BEHost["Render / Edge Host"]:::external

subgraph FAB["FastAPI Backend"]
direction TB
BEApp["FastAPI WebSocket Server\n(uvicorn)"]:::backend
BEWS["WebSocket Handler\n(bi-directional stream)"]:::backend
end

subgraph PIPE["Real-time CV + Analytics Pipeline"]
direction TB
Capture["Video Capture\n(camera/file/RTSP)"]:::pipeline
PreProc["OpenCV Preprocessing\n(edges + frame differencing)"]:::pipeline

subgraph INFM["Inference + Motion"]
direction TB
YOLO["YOLOv8 Inference\n(Ultralytics + PyTorch)"]:::pipeline
Flow["Optical Flow\n(Lucas-Kanade grid flow)"]:::pipeline
end

subgraph RDE["Risk / Decision Engine"]
direction TB
CPI["CPI Computation\n(crowd pressure index)"]:::algo
dCPI["ΔCPI Surge Detection\n(rolling ~3s window)"]:::algo
Chaos["Chaos Multiplier\n(std-dev of movement angles)"]:::algo
Choke["Choke Point Classification\n(Red Zone)"]:::algo
end

subgraph ROUT["Routing Engine"]
direction TB
AStar["A* Pathfinding\n(recompute safe routes)"]:::algo
end

Stream["Telemetry Serializer\n(JSON + optional encoded frames/bbox overlay)"]:::backend
end

BEDep["Backend Dependencies\n(FastAPI/uvicorn/opencv/ultralytics/torch/...)"]:::config

subgraph CS["Compute Substrate"]
direction TB
Accel["Hardware Acceleration\n(AMD EPYC / ROCm)"]:::compute
end
end

subgraph IL["Inputs Lane"]
direction TB
Vid["Video Source\n(CCTV/Drone/Recorded)"]:::external
end

%% Container relationships (primary flows)
U1 -->|"operates"| B1
V1 -->|"serves static assets"| B1
B1 -->|"loads"| FEEntry
FEEntry -->|"bootstraps"| FEShell
FEShell -->|"routes to"| PageDash
FEShell -->|"routes to"| PagePick
FEShell -->|"routes to"| PageArch
FEShell -->|"routes to"| PageLogin

FEEnv -.->|"configures WS URL"| FEShell
FEPkg -.->|"build-time deps"| FEShell
FEDeploy -.->|"deployment settings"| V1

%% WS link
PageDash <-->|"telemetry updates"| WS
PagePick -.->|"camera selection / scenario"| WS
PageDash -.->|"threshold config / start-stop"| WS

WS <-->|"WebSocket (wss) JSON + optional frames"| BEWS
BEWS -->|"invokes pipeline loop"| Capture

%% Vision pipeline
Vid -->|"frames (RGB) / stream"| Capture
Capture -->|"frames"| PreProc
PreProc -->|"processed frames"| YOLO
PreProc -->|"frame-to-frame deltas"| Flow
YOLO -->|"detections (bboxes/classes)"| CPI
Flow -->|"motion vectors"| CPI
PreProc -->|"edge density"| CPI

CPI -->|"CPI series"| dCPI
CPI -->|"movement stats"| Chaos
dCPI -->|"surge events"| Choke
Chaos -->|"chaos score"| Choke

Choke -->|"risk map / red zones"| AStar
AStar -->|"recommended route(s)"| Stream

CPI -->|"metrics"| Stream
dCPI -->|"alerts"| Stream
Chaos -->|"metrics"| Stream
Choke -->|"zone flags"| Stream

Stream -->|"telemetry JSON (CPI, ΔCPI, chaos, alerts, route)\n+ optional bbox overlay/frames"| BEWS

%% Compute + deployment notes
Accel -.->|"accelerates inference"| YOLO
BEHost -->|"runs"| BEApp
BEApp -->|"contains"| BEWS
BEDep -.->|"runtime deps"| BEApp

end

%% =======================
%% Level 3: Dynamic Sequence (Pipeline) - rendered as a vertical flow (flowchart-safe)
%% =======================
subgraph L3["Level 3: Dynamic Sequence (Pipeline)"]
direction TB

S1["1) Operator opens Dashboard / Picker"]:::external
S2["2) UI connects using VITE_WS_URL"]:::frontend
S3["3) WebSocket upgrade to FastAPI (/ws)"]:::network
S4["4) Real-time FPS loop begins"]:::backend
S5["5) Capture frame (RGB)"]:::pipeline
S6["6) OpenCV preprocess (edges + frame differencing)"]:::pipeline
S7["7) YOLOv8 inference (detections)"]:::pipeline
S8["8) Optical flow (motion vectors)"]:::pipeline
S9["9) Risk engine computes CPI / ΔCPI / Chaos / Choke"]:::algo
S10["10) A* recomputes safe route(s) if red zone"]:::algo
S11["11) Serialize telemetry (+ optional overlay/frame)"]:::backend
S12["12) Push JSON stream to UI; UI updates charts/alerts/route"]:::frontend
S13["13) UI may send control msg (camera/thresholds/start-stop)"]:::frontend

S1 --> S2 --> S3 --> S4 --> S5 --> S6
S6 --> S7 --> S9
S6 --> S8 --> S9
S9 --> S10 --> S11 --> S12
S12 --> S13 -.-> S3
end

%% =======================
%% Click events (mapped components)
%% =======================
click FEShell "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/src/App.tsx"
click FEEntry "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/src/main.tsx"
click PageDash "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/src/pages/Dashboard.tsx"
click PageArch "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/src/pages/Architecture.tsx"
click PageLogin "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/src/pages/Login.tsx"
click PagePick "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/src/pages/Picker.tsx"
click FEEnv "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/.env.example"
click FEPkg "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/package.json"
click FEDeploy "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/vercel.json"
click BEApp "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click BEWS "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click Stream "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click Capture "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click PreProc "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click YOLO "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click Flow "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click CPI "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click dCPI "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click Chaos "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click Choke "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click AStar "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/main.py"
click BEDep "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/backend/requirements.txt"
click V1 "https://github.com/atharvk-28/amd-slingshot/blob/main/CMADS_App/frontend/vercel.json"

%% README (system-level docs)
click System "https://github.com/atharvk-28/amd-slingshot/blob/main/README.md"

%% =======================
%% Styles
%% =======================
classDef external fill:#FFEDD5,stroke:#C2410C,color:#111827,stroke-width:1px
classDef system fill:#DBEAFE,stroke:#1D4ED8,color:#0B1220,stroke-width:2px
classDef frontend fill:#BFDBFE,stroke:#1D4ED8,color:#0B1220,stroke-width:1.5px
classDef backend fill:#93C5FD,stroke:#1E40AF,color:#0B1220,stroke-width:1.5px
classDef network fill:#E0E7FF,stroke:#4338CA,color:#0B1220,stroke-width:1.5px
classDef pipeline fill:#D1FAE5,stroke:#047857,color:#0B1220,stroke-width:1.2px
classDef algo fill:#A7F3D0,stroke:#065F46,color:#0B1220,stroke-width:1.2px
classDef compute fill:#E5E7EB,stroke:#374151,color:#111827,stroke-width:1.2px
classDef config fill:#FDE68A,stroke:#B45309,color:#111827,stroke-width:1.2px
```
