# ayazxdev/facetrace architecture

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

- Interactive diagram: https://gitdiagram.com/ayazxdev/facetrace
- Repository: https://github.com/ayazxdev/facetrace

## Overview

Drishti’s primary workflow is camera frames → per-camera detection, tracking, face identity and pose/action analysis → annotated live video and structured events, with rule-qualified threats persisted as alerts for review. Administrators also enroll and manage identities and submit recorded video for recognition; the interface exposes live streams, alert reports and administration. A separate frame-processing utility captions stored frames and indexes caption embeddings. Several backend sections are unsampled, so links for those behaviors are limited to documented capabilities and explicit excerpts.

Main entry points: [`backend/realtime_pipeline.py`](https://github.com/ayazxdev/facetrace/blob/main/backend/realtime_pipeline.py) (Camera pipeline), [`backend/main.py`](https://github.com/ayazxdev/facetrace/blob/main/backend/main.py) (HTTP and WS API), [`frontend/src/api/index.js`](https://github.com/ayazxdev/facetrace/blob/main/frontend/src/api/index.js) (API client), [`backend/db.py`](https://github.com/ayazxdev/facetrace/blob/main/backend/db.py) (Person records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Monitoring interface"]
  node_app["React application<br/>[App.jsx]"]
  node_api_client["API client<br/>[index.js]"]
  node_live_feed["Live pipeline feed"]
  node_alerts_ui["Alerts view<br/>[Alerts.jsx]"]
end

subgraph group_service["API and administration"]
  node_main["HTTP and WS API<br/>[main.py]"]
  node_admin["Admin operations<br/>[admin.py]"]
  node_video_upload["Video processing<br/>[main.py]"]
end

subgraph group_inference["Realtime inference"]
  node_pipeline["Camera pipeline"]
  node_face["Face detection<br/>[face_engine.py]"]
  node_pose_rules["Pose and action rules"]
  node_action["Weapon action scoring<br/>[action_engine.py]"]
end

subgraph group_records["Identity and alerts"]
  node_people[("Person records<br/>[db.py]")]
  node_alerts[("Alert records<br/>[db.py]")]
end

subgraph group_frames["Frame intelligence"]
  node_frame_processor["Frame captioning<br/>[process_frames.py]"]
  node_frame_config["Frame settings<br/>[config.py]"]
end

node_operator(("Operator"))
node_camera(("Camera feeds"))

node_operator -->|"uses"| node_app
node_app -->|"requests"| node_api_client
node_api_client -->|"calls endpoints"| node_main
node_live_feed -->|"opens WebSocket"| node_main
node_main -->|"starts and streams"| node_pipeline
node_camera -->|"supplies frames"| node_pipeline
node_pipeline -->|"detects and embeds"| node_face
node_pipeline -->|"classifies actions"| node_pose_rules
node_pipeline -->|"scores weapons"| node_action
node_pipeline -->|"loads identities"| node_people
node_pipeline -->|"writes alerts"| node_alerts
node_main -->|"manages identities"| node_people
node_video_upload -->|"matches faces"| node_people
node_live_feed -->|"shows events"| node_alerts_ui
node_alerts_ui -->|"fetches alerts"| node_api_client
node_api_client -->|"requests reports"| node_main
node_main -->|"reads alerts"| node_alerts
node_frame_processor -->|"reads settings"| node_frame_config

click node_app "https://github.com/ayazxdev/facetrace/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/ayazxdev/facetrace/blob/main/frontend/src/api/index.js"
click node_live_feed "https://github.com/ayazxdev/facetrace/blob/main/frontend/src/components/RealtimePipelineFeed.jsx"
click node_alerts_ui "https://github.com/ayazxdev/facetrace/blob/main/frontend/src/pages/Alerts.jsx"
click node_main "https://github.com/ayazxdev/facetrace/blob/main/backend/main.py"
click node_admin "https://github.com/ayazxdev/facetrace/blob/main/backend/admin.py"
click node_video_upload "https://github.com/ayazxdev/facetrace/blob/main/backend/main.py"
click node_pipeline "https://github.com/ayazxdev/facetrace/blob/main/backend/realtime_pipeline.py"
click node_face "https://github.com/ayazxdev/facetrace/blob/main/backend/face_engine.py"
click node_pose_rules "https://github.com/ayazxdev/facetrace/blob/main/backend/utils_pose_rules.py"
click node_action "https://github.com/ayazxdev/facetrace/blob/main/backend/action_engine.py"
click node_people "https://github.com/ayazxdev/facetrace/blob/main/backend/db.py"
click node_alerts "https://github.com/ayazxdev/facetrace/blob/main/backend/db.py"
click node_frame_processor "https://github.com/ayazxdev/facetrace/blob/main/amg_chatbot/process_frames.py"
click node_frame_config "https://github.com/ayazxdev/facetrace/blob/main/amg_chatbot/config.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_app,node_api_client,node_live_feed,node_alerts_ui toneBlue
class node_main,node_admin,node_video_upload toneAmber
class node_pipeline,node_face,node_pose_rules,node_action toneMint
class node_people,node_alerts toneRose
class node_frame_processor,node_frame_config,node_operator,node_camera toneIndigo
```

## Components

### Monitoring interface

- [React application](https://github.com/ayazxdev/facetrace/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/ayazxdev/facetrace/blob/main/frontend/src/api/index.js): `frontend/src/api/index.js`
- [Live pipeline feed](https://github.com/ayazxdev/facetrace/blob/main/frontend/src/components/RealtimePipelineFeed.jsx): `frontend/src/components/RealtimePipelineFeed.jsx`
- [Alerts view](https://github.com/ayazxdev/facetrace/blob/main/frontend/src/pages/Alerts.jsx): `frontend/src/pages/Alerts.jsx`

### API and administration

- [HTTP and WS API](https://github.com/ayazxdev/facetrace/blob/main/backend/main.py): `backend/main.py`
- [Admin operations](https://github.com/ayazxdev/facetrace/blob/main/backend/admin.py): `backend/admin.py`
- [Video processing](https://github.com/ayazxdev/facetrace/blob/main/backend/main.py): `backend/main.py`

### Realtime inference

- [Camera pipeline](https://github.com/ayazxdev/facetrace/blob/main/backend/realtime_pipeline.py): `backend/realtime_pipeline.py`
- [Face detection](https://github.com/ayazxdev/facetrace/blob/main/backend/face_engine.py): `backend/face_engine.py`
- [Pose and action rules](https://github.com/ayazxdev/facetrace/blob/main/backend/utils_pose_rules.py): `backend/utils_pose_rules.py`
- [Weapon action scoring](https://github.com/ayazxdev/facetrace/blob/main/backend/action_engine.py): `backend/action_engine.py`

### Identity and alerts

- [Person records](https://github.com/ayazxdev/facetrace/blob/main/backend/db.py): `backend/db.py`
- [Alert records](https://github.com/ayazxdev/facetrace/blob/main/backend/db.py): `backend/db.py`

### Frame intelligence

- [Frame captioning](https://github.com/ayazxdev/facetrace/blob/main/amg_chatbot/process_frames.py): `amg_chatbot/process_frames.py`
- [Frame settings](https://github.com/ayazxdev/facetrace/blob/main/amg_chatbot/config.py): `amg_chatbot/config.py`

### Other components

- **Operator**
- **Camera feeds**

## Connections

- Operator → React application: uses
- React application → API client: requests
- API client → HTTP and WS API: calls endpoints
- Live pipeline feed → HTTP and WS API: opens WebSocket
- HTTP and WS API → Camera pipeline: starts and streams
- Camera feeds → Camera pipeline: supplies frames
- Camera pipeline → Face detection: detects and embeds
- Camera pipeline → Pose and action rules: classifies actions
- Camera pipeline → Weapon action scoring: scores weapons
- Camera pipeline → Person records: loads identities
- Camera pipeline → Alert records: writes alerts
- HTTP and WS API → Person records: manages identities
- Video processing → Person records: matches faces
- Live pipeline feed → Alerts view: shows events
- Alerts view → API client: fetches alerts
- API client → HTTP and WS API: requests reports
- HTTP and WS API → Alert records: reads alerts
- Frame captioning → Frame settings: reads settings