# narukavya/ai-traffic-sign-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/narukavya/ai-traffic-sign-recognition
- Repository: https://github.com/narukavya/ai-traffic-sign-recognition

## Overview

This is a traffic-sign recognition project with an interactive Streamlit classifier and separate scripts for preparing data, training and evaluating a CNN, and inspecting training history. The main user workflow uploads an image, resizes and normalizes it, runs inference, then displays the predicted sign and confidence. Training and evaluation are standalone scripts, not stages invoked by the app. Gemini explanation code exists, but the app explicitly disables it. Artifact links reflect matching filenames in the shown scripts; the README is empty and generated artifacts are absent from the tree.

Main entry points: [`src/train.py`](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/train.py) (CNN training), [`app.py`](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py) (CNN inference), [`src/evaluate.py`](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/evaluate.py) (Model evaluation), [`src/preprocess.py`](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/preprocess.py) (Dataset preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_user_flow["Image classification"]
  node_upload["Streamlit interface<br/>[app.py]"]
  node_image_prep["Image preparation<br/>[app.py]"]
  node_inference["CNN inference<br/>[app.py]"]
  node_classification["Prediction display<br/>[app.py]"]
  node_cli_prediction["CLI prediction<br/>[predict.py]"]
end

subgraph group_model_lifecycle["Model lifecycle"]
  node_training_data["Prepared datasets"]
  node_preprocessing["Dataset preprocessing<br/>[preprocess.py]"]
  node_training["CNN training<br/>[train.py]"]
  node_model_artifact["Trained CNN"]
end

subgraph group_analysis["Evaluation and analysis"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_history_artifact["Training history"]
  node_history_plot["History plots<br/>[plot_history.py]"]
end

subgraph group_integration["Optional explanation"]
  node_gemini_helper["Sign explanation helper<br/>[gemini_helper.py]"]
end

node_user(("Image uploader"))
node_gemini{{"Gemini API"}}

node_user -->|"uploads image"| node_upload
node_upload -->|"prepares image"| node_image_prep
node_image_prep -->|"supplies image"| node_inference
node_inference -->|"displays scores"| node_classification
node_preprocessing -->|"writes arrays"| node_training_data
node_training_data -->|"loads arrays"| node_training
node_training -->|"saves model"| node_model_artifact
node_model_artifact -->|"loads model"| node_inference
node_training_data -->|"loads test arrays"| node_evaluation
node_model_artifact -->|"loads model"| node_evaluation
node_training -->|"saves history"| node_history_artifact
node_history_artifact -->|"loads history"| node_history_plot
node_model_artifact -->|"loads model"| node_cli_prediction
node_gemini_helper -->|"requests explanation"| node_gemini

click node_upload "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py"
click node_image_prep "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py"
click node_inference "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py"
click node_classification "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py"
click node_preprocessing "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/preprocess.py"
click node_training "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/train.py"
click node_evaluation "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/evaluate.py"
click node_history_plot "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/plot_history.py"
click node_cli_prediction "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/predict.py"
click node_gemini_helper "https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/gemini_helper.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_upload,node_image_prep,node_inference,node_classification,node_cli_prediction toneBlue
class node_training_data,node_preprocessing,node_training,node_model_artifact toneAmber
class node_evaluation,node_history_artifact,node_history_plot,node_gemini toneMint
class node_gemini_helper toneRose
class node_user toneIndigo
```

## Components

### Image classification

- [Streamlit interface](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py): `app.py`
- [Image preparation](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py): `app.py`
- [CNN inference](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py): `app.py`
- [Prediction display](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/app.py): `app.py`
- [CLI prediction](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/predict.py): `src/predict.py`

### Model lifecycle

- **Prepared datasets**
- [Dataset preprocessing](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/preprocess.py): `src/preprocess.py`
- [CNN training](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/train.py): `src/train.py`
- **Trained CNN**

### Evaluation and analysis

- [Model evaluation](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/evaluate.py): `src/evaluate.py`
- **Training history**
- [History plots](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/plot_history.py): `src/plot_history.py`

### Optional explanation

- [Sign explanation helper](https://github.com/narukavya/ai-traffic-sign-recognition/blob/master/src/gemini_helper.py): `src/gemini_helper.py`

### Other components

- **Image uploader**
- **Gemini API**

## Connections

- Image uploader → Streamlit interface: uploads image (evidence: `app.py`)
- Streamlit interface → Image preparation: prepares image (evidence: `app.py`)
- Image preparation → CNN inference: supplies image (evidence: `app.py`)
- CNN inference → Prediction display: displays scores (evidence: `app.py`)
- Dataset preprocessing → Prepared datasets: writes arrays (evidence: `src/preprocess.py`)
- Prepared datasets → CNN training: loads arrays (evidence: `src/train.py`)
- CNN training → Trained CNN: saves model (evidence: `src/train.py`)
- Trained CNN → CNN inference: loads model (evidence: `app.py`)
- Prepared datasets → Model evaluation: loads test arrays (evidence: `src/evaluate.py`)
- Trained CNN → Model evaluation: loads model (evidence: `src/evaluate.py`)
- CNN training → Training history: saves history (evidence: `src/train.py`)
- Training history → History plots: loads history (evidence: `src/plot_history.py`)
- Trained CNN → CLI prediction: loads model (evidence: `src/predict.py`)
- Sign explanation helper → Gemini API: requests explanation (evidence: `src/gemini_helper.py`)
