# 4run4v/citytrack-ai architecture

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

- Interactive diagram: https://gitdiagram.com/4run4v/citytrack-ai
- Repository: https://github.com/4run4v/citytrack-ai

## Overview

CityTrack AI is intended as a city-scale, multi-camera vehicle and plate tracking system with traffic analytics and a command-center frontend. The documented domain stages include camera streams, vehicle detection and tracking, ANPR, and analytics; the repository also includes a FastAPI backend and PostgreSQL/PostGIS schema. Sampled implementation is mostly placeholder code, so component-to-component runtime wiring is not established here. The only concrete API behavior sampled is the backend health endpoint.

Main entry points: [`backend/main.py`](https://github.com/4run4v/citytrack-ai/blob/main/backend/main.py) (FastAPI Backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_camera["Camera Ingestion"]
  node_camera_manager["Stream Manager<br/>[camera_manager.py]"]
end

subgraph group_vision["Vision and ANPR"]
  node_vehicle_detector["Vehicle Detection"]
  node_tracker["Vehicle Tracking<br/>[tracker.py]"]
  node_plate_detector["Plate Detection<br/>[plate_detector.py]"]
  node_preprocessing["Image Preprocessing<br/>[preprocessing.py]"]
  node_ocr["Plate OCR<br/>[ocr.py]"]
  node_plate_validator["Plate Normalization<br/>[plate_validator.py]"]
  node_models["Local AI Models"]
end

subgraph group_analytics["Traffic Analytics"]
  node_congestion["Congestion<br/>[congestion.py]"]
  node_density["Traffic Density<br/>[density.py]"]
  node_od_matrix["OD Matrix<br/>[od_matrix.py]"]
  node_speed["Speed Analytics<br/>[speed.py]"]
  node_traffic["Traffic Analytics<br/>[traffic.py]"]
end

subgraph group_appdata["Application and Data"]
  node_frontend["Command Center"]
  node_backend["FastAPI Backend<br/>[main.py]"]
  node_database[("PostgreSQL/PostGIS<br/>[schema.sql]")]
end

node_camera_source(("IP Cameras"))
node_api_client(("HTTP Client"))

node_api_client -->|"requests health"| node_backend
node_backend -->|"returns status"| node_api_client

click node_camera_manager "https://github.com/4run4v/citytrack-ai/blob/main/camera/camera_manager.py"
click node_vehicle_detector "https://github.com/4run4v/citytrack-ai/blob/main/vision/detection/vehicle_detector.py"
click node_tracker "https://github.com/4run4v/citytrack-ai/blob/main/vision/tracking/tracker.py"
click node_plate_detector "https://github.com/4run4v/citytrack-ai/blob/main/anpr/plate_detector.py"
click node_preprocessing "https://github.com/4run4v/citytrack-ai/blob/main/anpr/preprocessing.py"
click node_ocr "https://github.com/4run4v/citytrack-ai/blob/main/anpr/ocr.py"
click node_plate_validator "https://github.com/4run4v/citytrack-ai/blob/main/anpr/plate_validator.py"
click node_congestion "https://github.com/4run4v/citytrack-ai/blob/main/analytics/congestion.py"
click node_density "https://github.com/4run4v/citytrack-ai/blob/main/analytics/density.py"
click node_od_matrix "https://github.com/4run4v/citytrack-ai/blob/main/analytics/od_matrix.py"
click node_speed "https://github.com/4run4v/citytrack-ai/blob/main/analytics/speed.py"
click node_traffic "https://github.com/4run4v/citytrack-ai/blob/main/analytics/traffic.py"
click node_frontend "https://github.com/4run4v/citytrack-ai/tree/main/frontend"
click node_backend "https://github.com/4run4v/citytrack-ai/blob/main/backend/main.py"
click node_database "https://github.com/4run4v/citytrack-ai/blob/main/database/schema.sql"
click node_models "https://github.com/4run4v/citytrack-ai/tree/main/models"

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_camera_manager,node_api_client toneBlue
class node_vehicle_detector,node_tracker,node_plate_detector,node_preprocessing,node_ocr,node_plate_validator,node_models toneAmber
class node_congestion,node_density,node_od_matrix,node_speed,node_traffic toneMint
class node_frontend,node_backend,node_database toneRose
class node_camera_source toneIndigo
```

## Components

### Camera Ingestion

- [Stream Manager](https://github.com/4run4v/citytrack-ai/blob/main/camera/camera_manager.py): `camera/camera_manager.py`

### Vision and ANPR

- [Vehicle Detection](https://github.com/4run4v/citytrack-ai/blob/main/vision/detection/vehicle_detector.py): `vision/detection/vehicle_detector.py`
- [Vehicle Tracking](https://github.com/4run4v/citytrack-ai/blob/main/vision/tracking/tracker.py): `vision/tracking/tracker.py`
- [Plate Detection](https://github.com/4run4v/citytrack-ai/blob/main/anpr/plate_detector.py): `anpr/plate_detector.py`
- [Image Preprocessing](https://github.com/4run4v/citytrack-ai/blob/main/anpr/preprocessing.py): `anpr/preprocessing.py`
- [Plate OCR](https://github.com/4run4v/citytrack-ai/blob/main/anpr/ocr.py): `anpr/ocr.py`
- [Plate Normalization](https://github.com/4run4v/citytrack-ai/blob/main/anpr/plate_validator.py): `anpr/plate_validator.py`
- [Local AI Models](https://github.com/4run4v/citytrack-ai/tree/main/models): `models`

### Traffic Analytics

- [Congestion](https://github.com/4run4v/citytrack-ai/blob/main/analytics/congestion.py): `analytics/congestion.py`
- [Traffic Density](https://github.com/4run4v/citytrack-ai/blob/main/analytics/density.py): `analytics/density.py`
- [OD Matrix](https://github.com/4run4v/citytrack-ai/blob/main/analytics/od_matrix.py): `analytics/od_matrix.py`
- [Speed Analytics](https://github.com/4run4v/citytrack-ai/blob/main/analytics/speed.py): `analytics/speed.py`
- [Traffic Analytics](https://github.com/4run4v/citytrack-ai/blob/main/analytics/traffic.py): `analytics/traffic.py`

### Application and Data

- [Command Center](https://github.com/4run4v/citytrack-ai/tree/main/frontend): `frontend`
- [FastAPI Backend](https://github.com/4run4v/citytrack-ai/blob/main/backend/main.py): `backend/main.py`
- [PostgreSQL/PostGIS](https://github.com/4run4v/citytrack-ai/blob/main/database/schema.sql): `database/schema.sql`

### Other components

- **IP Cameras**
- **HTTP Client**

## Connections

- HTTP Client → FastAPI Backend: requests health
- FastAPI Backend → HTTP Client: returns status