# coderyasa089/trafficsense architecture

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

- Interactive diagram: https://gitdiagram.com/coderyasa089/trafficsense
- Repository: https://github.com/coderyasa089/trafficsense

## Overview

TrafficSense processes video feeds through detection, tracking, and violation rules, then captures evidence and submits violation records to a FastAPI backend. The backend stores records in SQLite and supports retrieval and ticket generation; the README also describes a dashboard and coordinated multi-camera processing. The backend and AI path are supported by sampled source. The dashboard implementation was not sampled, so its connection to backend APIs is not asserted.

Main entry points: [`ai_engine/main_engine.py`](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/main_engine.py) (Traffic Engine), [`backend/main.py`](https://github.com/coderyasa089/trafficsense/blob/main/backend/main.py) (REST API), [`ai_engine/utils/api_client.py`](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/utils/api_client.py) (Violation API Client), [`ai_engine/multi_cam.py`](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/multi_cam.py) (Multi-Camera Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Camera Processing"]
  node_multi_cam["Multi-Camera Runner<br/>[multi_cam.py]"]
  node_traffic_engine["Traffic Engine<br/>[main_engine.py]"]
end

subgraph group_analysis["Violation Analysis"]
  node_detector["Vehicle Detector<br/>[detector.py]"]
  node_tracker["Object Tracker<br/>[tracker.py]"]
  node_rules["Violation Rules<br/>[rule_engine.py]"]
  node_evidence["Evidence Capture<br/>[evidence.py]"]
end

subgraph group_service["Backend Services"]
  node_api_client["Violation API Client<br/>[api_client.py]"]
  node_backend_api["REST API<br/>[main.py]"]
end

subgraph group_records["Violation Records"]
  node_sqlite[("Violation Store<br/>[database.py]")]
  node_ticket["Ticket Generation<br/>[main.py]"]
end

subgraph group_interface["Dashboard"]
  node_dashboard["HTML Dashboard<br/>[index.html]"]
end

node_video_feeds(("Video Feeds"))

node_video_feeds -->|"provides frames"| node_traffic_engine
node_multi_cam -->|"starts per feed"| node_traffic_engine
node_traffic_engine -->|"detects objects"| node_detector
node_traffic_engine -->|"updates tracks"| node_tracker
node_traffic_engine -->|"evaluates tracks"| node_rules
node_traffic_engine -->|"saves snapshots"| node_evidence
node_traffic_engine -->|"queues violations"| node_api_client
node_api_client -->|"posts reports"| node_backend_api
node_backend_api -->|"reads and writes"| node_sqlite
node_backend_api -->|"generates tickets"| node_ticket

click node_multi_cam "https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/multi_cam.py"
click node_traffic_engine "https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/main_engine.py"
click node_detector "https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/core/detector.py"
click node_tracker "https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/core/tracker.py"
click node_rules "https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/core/rule_engine.py"
click node_evidence "https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/evidence/evidence.py"
click node_api_client "https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/utils/api_client.py"
click node_backend_api "https://github.com/coderyasa089/trafficsense/blob/main/backend/main.py"
click node_sqlite "https://github.com/coderyasa089/trafficsense/blob/main/backend/database.py"
click node_ticket "https://github.com/coderyasa089/trafficsense/blob/main/backend/main.py"
click node_dashboard "https://github.com/coderyasa089/trafficsense/blob/main/frontend/index.html"

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_multi_cam,node_traffic_engine toneBlue
class node_detector,node_tracker,node_rules,node_evidence toneAmber
class node_api_client,node_backend_api toneMint
class node_sqlite,node_ticket toneRose
class node_dashboard,node_video_feeds toneIndigo
```

## Components

### Camera Processing

- [Multi-Camera Runner](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/multi_cam.py): `ai_engine/multi_cam.py`
- [Traffic Engine](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/main_engine.py): `ai_engine/main_engine.py`

### Violation Analysis

- [Vehicle Detector](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/core/detector.py): `ai_engine/core/detector.py`
- [Object Tracker](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/core/tracker.py): `ai_engine/core/tracker.py`
- [Violation Rules](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/core/rule_engine.py): `ai_engine/core/rule_engine.py`
- [Evidence Capture](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/evidence/evidence.py): `ai_engine/evidence/evidence.py`

### Backend Services

- [Violation API Client](https://github.com/coderyasa089/trafficsense/blob/main/ai_engine/utils/api_client.py): `ai_engine/utils/api_client.py`
- [REST API](https://github.com/coderyasa089/trafficsense/blob/main/backend/main.py): `backend/main.py`

### Violation Records

- [Violation Store](https://github.com/coderyasa089/trafficsense/blob/main/backend/database.py): `backend/database.py`
- [Ticket Generation](https://github.com/coderyasa089/trafficsense/blob/main/backend/main.py): `backend/main.py`

### Dashboard

- [HTML Dashboard](https://github.com/coderyasa089/trafficsense/blob/main/frontend/index.html): `frontend/index.html`

### Other components

- **Video Feeds**

## Connections

- Video Feeds → Traffic Engine: provides frames (evidence: `ai_engine/main_engine.py`)
- Multi-Camera Runner → Traffic Engine: starts per feed (evidence: `ai_engine/multi_cam.py`)
- Traffic Engine → Vehicle Detector: detects objects (evidence: `ai_engine/main_engine.py`)
- Traffic Engine → Object Tracker: updates tracks (evidence: `ai_engine/main_engine.py`)
- Traffic Engine → Violation Rules: evaluates tracks (evidence: `ai_engine/main_engine.py`)
- Traffic Engine → Evidence Capture: saves snapshots (evidence: `ai_engine/main_engine.py`)
- Traffic Engine → Violation API Client: queues violations (evidence: `ai_engine/main_engine.py`)
- Violation API Client → REST API: posts reports (evidence: `ai_engine/utils/api_client.py`)
- REST API → Violation Store: reads and writes (evidence: `backend/main.py`)
- REST API → Ticket Generation: generates tickets (evidence: `backend/main.py`)