# ibavi-git/trafficiq architecture

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

- Interactive diagram: https://gitdiagram.com/ibavi-git/trafficiq
- Repository: https://github.com/ibavi-git/trafficiq

## Overview

TrafficIQ’s present product is a CPU-oriented traffic-video analysis toolkit: users run command-line tools on images or videos to obtain detections, persistent tracks, counts, congestion/anomaly analysis, or feature artifacts. Its implemented AI-core also includes ViT extraction, YOLO–ViT fusion, and Grad-CAM generation. The README describes a future FastAPI/dashboard and optimization/deployment plans, but those components are absent from this tree, so they are not modeled as implemented services. Several module-to-module links rely on the README or SOURCE INDEX; unsampled internals are not assumed.

Main entry points: [`ai-core/fusion/fuse.py`](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/fusion/fuse.py) (YOLO–ViT fusion), [`ai-core/detection/classes.py`](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/detection/classes.py) (Vehicle classes), [`ai-core/traffic/analyze.py`](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/traffic/analyze.py) (Congestion and anomalies), [`ai-core/detection/detect.py`](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/detection/detect.py) (YOLO detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Vehicle Vision"]
  node_classes["Vehicle classes<br/>[classes.py]"]
  node_detect["YOLO detection<br/>[detect.py]"]
  node_track["ByteTrack tracking<br/>[track.py]"]
end

subgraph group_analysis["Traffic Analysis"]
  node_count["Line-crossing counts<br/>[count.py]"]
  node_traffic["Congestion and anomalies<br/>[analyze.py]"]
end

subgraph group_context["Scene Context"]
  node_vit["ViT embeddings<br/>[extract.py]"]
  node_fusion["YOLO–ViT fusion<br/>[fuse.py]"]
  node_visualize["Fusion visualization<br/>[visualize.py]"]
  node_gradcam["Grad-CAM explanations<br/>[gradcam.py]"]
end

subgraph group_operations["Performance Tools"]
  node_benchmark["CPU benchmark<br/>[benchmark.py]"]
end

node_operator(("Traffic operator"))
node_video["Image or video"]
node_results["Analysis artifacts"]

node_operator -->|"provides"| node_video
node_video -->|"input to"| node_detect
node_video -->|"input to"| node_track
node_video -->|"input to"| node_count
node_video -->|"input to"| node_traffic
node_video -->|"sampled by"| node_vit
node_video -->|"input to"| node_fusion
node_video -->|"input to"| node_gradcam
node_video -->|"benchmarked by"| node_benchmark
node_detect -->|"uses classes"| node_classes
node_track -->|"uses classes"| node_classes
node_count -->|"uses classes"| node_classes
node_traffic -->|"uses classes"| node_classes
node_fusion -->|"uses classes"| node_classes
node_fusion -->|"loads embeddings"| node_vit
node_fusion -->|"uses congestion scoring"| node_traffic
node_detect -->|"writes annotated output"| node_results
node_track -->|"writes tracked video"| node_results
node_count -->|"writes counts"| node_results
node_traffic -->|"reports traffic metrics"| node_results
node_vit -->|"saves embeddings"| node_results
node_fusion -->|"saves fused features"| node_results
node_gradcam -->|"writes overlays"| node_results
node_benchmark -->|"records baseline"| node_results

click node_classes "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/detection/classes.py"
click node_detect "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/detection/detect.py"
click node_track "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/tracking/track.py"
click node_count "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/tracking/count.py"
click node_traffic "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/traffic/analyze.py"
click node_vit "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/vit/extract.py"
click node_fusion "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/fusion/fuse.py"
click node_visualize "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/fusion/visualize.py"
click node_gradcam "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/xai/gradcam.py"
click node_benchmark "https://github.com/ibavi-git/trafficiq/blob/main/ai-core/benchmark/benchmark.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_classes,node_detect,node_track toneBlue
class node_count,node_traffic toneAmber
class node_vit,node_fusion,node_visualize,node_gradcam toneMint
class node_benchmark toneRose
class node_operator,node_video,node_results toneIndigo
```

## Components

### Vehicle Vision

- [Vehicle classes](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/detection/classes.py): `ai-core/detection/classes.py`
- [YOLO detection](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/detection/detect.py): `ai-core/detection/detect.py`
- [ByteTrack tracking](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/tracking/track.py): `ai-core/tracking/track.py`

### Traffic Analysis

- [Line-crossing counts](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/tracking/count.py): `ai-core/tracking/count.py`
- [Congestion and anomalies](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/traffic/analyze.py): `ai-core/traffic/analyze.py`

### Scene Context

- [ViT embeddings](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/vit/extract.py): `ai-core/vit/extract.py`
- [YOLO–ViT fusion](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/fusion/fuse.py): `ai-core/fusion/fuse.py`
- [Fusion visualization](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/fusion/visualize.py): `ai-core/fusion/visualize.py`
- [Grad-CAM explanations](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/xai/gradcam.py): `ai-core/xai/gradcam.py`

### Performance Tools

- [CPU benchmark](https://github.com/ibavi-git/trafficiq/blob/main/ai-core/benchmark/benchmark.py): `ai-core/benchmark/benchmark.py`

### Other components

- **Traffic operator**
- **Image or video**
- **Analysis artifacts**

## Connections

- Traffic operator → Image or video: provides (evidence: `README.md`)
- Image or video → YOLO detection: input to (evidence: `README.md`)
- Image or video → ByteTrack tracking: input to (evidence: `README.md`)
- Image or video → Line-crossing counts: input to (evidence: `README.md`)
- Image or video → Congestion and anomalies: input to (evidence: `README.md`)
- Image or video → ViT embeddings: sampled by (evidence: `README.md`)
- Image or video → YOLO–ViT fusion: input to (evidence: `ai-core/fusion/fuse.py`)
- Image or video → Grad-CAM explanations: input to (evidence: `ai-core/xai/gradcam.py`)
- Image or video → CPU benchmark: benchmarked by (evidence: `README.md`)
- YOLO detection → Vehicle classes: uses classes (evidence: `ai-core/detection/detect.py`)
- ByteTrack tracking → Vehicle classes: uses classes (evidence: `ai-core/tracking/track.py`)
- Line-crossing counts → Vehicle classes: uses classes (evidence: `ai-core/tracking/count.py`)
- Congestion and anomalies → Vehicle classes: uses classes (evidence: `ai-core/traffic/analyze.py`)
- YOLO–ViT fusion → Vehicle classes: uses classes (evidence: `ai-core/fusion/fuse.py`)
- YOLO–ViT fusion → ViT embeddings: loads embeddings (evidence: `ai-core/fusion/fuse.py`)
- YOLO–ViT fusion → Congestion and anomalies: uses congestion scoring (evidence: `ai-core/fusion/fuse.py`)
- YOLO detection → Analysis artifacts: writes annotated output (evidence: `README.md`)
- ByteTrack tracking → Analysis artifacts: writes tracked video (evidence: `README.md`)
- Line-crossing counts → Analysis artifacts: writes counts (evidence: `README.md`)
- Congestion and anomalies → Analysis artifacts: reports traffic metrics (evidence: `README.md`)
- ViT embeddings → Analysis artifacts: saves embeddings (evidence: `ai-core/vit/extract.py`)
- YOLO–ViT fusion → Analysis artifacts: saves fused features (evidence: `ai-core/fusion/fuse.py`)
- Grad-CAM explanations → Analysis artifacts: writes overlays (evidence: `ai-core/xai/gradcam.py`)
- CPU benchmark → Analysis artifacts: records baseline (evidence: `README.md`)
