# lynguyenminh/cs114.m11.vietnam-traffic-sign-detection architecture

> Architecture diagram of the GitHub repository lynguyenminh/cs114.m11.vietnam-traffic-sign-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection
- Repository: https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection

## Overview

##### Project type and purpose
- This is a full-stack, ML-powered web application whose goal is “Phát hiện và nhận dạng 50+ biển báo giao thông” (detect and recognize 50+ Vietnamese road signs).
- The top-level “Final_Project/API” folder implements a Flask (or similar Python) REST service with a simple HTML/JS frontend. The “Source code” notebooks show your training/inference experiments (YOLOv4, YOLOv5).

##### File structure
- Final_Project/API
- app.py – the main HTTP server (Flask)
- detect.py – inference entrypoint (loads model, runs detection)
- export.py – exports a model to a deployable format
- models/ – YOLO model definitions and config (yolov5s.yaml, common.py, yolo.py, tf.py, experimental.py)
- utils/ – helper routines (dataloaders, augmentations, loss, metrics, plotting, etc.)
- data/coco128.yaml – dataset/class definitions
- static/ + templates/ – frontend assets (HTML, CSS, JS) and result display
- Dockerfile, run.sh, test/Dockerfile – containerization and launch scripts
- Source code notebooks are separate and used offline for data collection and model training.

##### Main components and their relationships
- Browser / User Interface
- index.html + index.js form a simple upload UI.
- On form submission, JavaScript issues an HTTP POST/GET to the API endpoint (e.g. /detect).
- API Server (app.py)
- Receives HTTP requests, routes them to detect.py or export.py.
- Renders templates (output.html) or returns JSON for frontend to consume.
- Inference Engine
- detect.py loads a pre-trained YOLO model (from models/) using torch_utils, common, etc.
- Data & Config
- data/coco128.yaml defines classes and dataset paths.
- yolov5s.yaml (and other model configs) define architecture/hyperparameters.
- Deployment / DevOps
- Dockerfile builds a container image with Python, dependencies (requirements.txt) and your API.
- run.sh (or docker-compose) starts the server.
- test/Dockerfile can be used for CI or staging.

##### Architectural patterns and design principles
- MVC-like separation:
- Model = your ML code + weights (models/, utils/)
- View = HTML templates (templates/), static assets (static/)
- Controller = app.py routes + detect.py logic
- Modularization: each utility (dataloaders, augmentations, metrics) lives in its own module.
- Containerization ensures environment reproducibility.

##### Detail
- Every folder (models, utils, data) is represented if it plays a runtime role.
- Optional “Offline Training” path as a separate notebook component that writes model weights used by the inference pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    Browser["Web Browser/User"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container" 
        style DockerContainer stroke:#999,stroke-width:2px,fill:transparent
        DockerContainer[[ ]] 

        %% Frontend Layer
        subgraph "Frontend UI" 
            direction TB
            IndexHTML["index.html"]:::frontend
            IndexJS["index.js"]:::frontend
            IndexCSS["index.css"]:::frontend
            OutputHTML["output.html"]:::frontend
            ResultTXT["result.txt"]:::frontend
        end

        %% Backend API Layer
        subgraph "Flask API Server" 
            direction TB
            AppPy["app.py"]:::backend
            DetectPy["detect.py"]:::ml
            ExportPy["export.py"]:::ml
        end

        %% Inference Module
        subgraph "YOLO Inference Module" 
            direction TB
            Loader["Model Loader"]:::ml
            Preprocessor["Pre-processor"]:::ml
            Postprocessor["Post-processor"]:::ml
            subgraph "Model Definitions" 
                direction TB
                Yaml["yolov5s.yaml"]:::ml
                CommonPY["common.py"]:::ml
                YoloPY["yolo.py"]:::ml
                TfPY["tf.py"]:::ml
                ExpPY["experimental.py"]:::ml
            end
            subgraph "Utility Modules" 
                direction TB
                Activations["activations.py"]:::ml
                Augmentations["augmentations.py"]:::ml
                Autoanchor["autoanchor.py"]:::ml
                Autobatch["autobatch.py"]:::ml
                Benchmarks["benchmarks.py"]:::ml
                Callbacks["callbacks.py"]:::ml
                Dataloaders["dataloaders.py"]:::ml
                Downloads["downloads.py"]:::ml
                General["general.py"]:::ml
                Loss["loss.py"]:::ml
                Metrics["metrics.py"]:::ml
                Plots["plots.py"]:::ml
                TorchUtils["torch_utils.py"]:::ml
            end
        end

        %% Configuration/Data
        subgraph "Config/Data" 
            direction TB
            CocoYAML["coco128.yaml"]:::data
        end
    end

    %% Offline Training
    subgraph "Offline Training" 
        direction TB
        Yolov4NB["Yolov4_notebook.ipynb"]:::offline
        Yolov5NB["Yolov5_notebook.ipynb"]:::offline
    end

    %% Connections
    Browser -->|"uploads image"| IndexHTML
    IndexHTML -->|"serves UI"| IndexJS
    IndexJS -->|"POST /api/detect"| AppPy
    AppPy -->|"calls detect.py"| DetectPy
    AppPy -->|"calls export.py"| ExportPy
    DetectPy -->|"loads model"| Loader
    Loader --> Preprocessor
    Preprocessor --> Yaml
    Preprocessor --> CommonPY
    Preprocessor --> YoloPY
    Preprocessor --> TfPY
    Preprocessor --> ExpPY
    Loader --> Activations
    Loader --> Augmentations
    Loader --> Autoanchor
    Loader --> Autobatch
    Loader --> Benchmarks
    Loader --> Callbacks
    Loader --> Dataloaders
    Loader --> Downloads
    Loader --> General
    Loader --> Loss
    Loader --> Metrics
    Loader --> Plots
    Loader --> TorchUtils
    Postprocessor -->|"uses config"| CocoYAML
    DetectPy --> Postprocessor
    Postprocessor --> AppPy
    AppPy -->|"returns JSON or renders"| OutputHTML
    OutputHTML -->|"displays results"| Browser

    Yolov4NB -->|"produces weights"| Loader
    Yolov5NB -->|"produces weights"| Loader

    %% Click Events
    click IndexHTML "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/templates/index.html"
    click OutputHTML "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/templates/output.html"
    click IndexJS "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/static/index.js"
    click IndexCSS "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/static/index.css"
    click ResultTXT "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/static/result.txt"
    click AppPy "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/app.py"
    click DetectPy "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/detect.py"
    click ExportPy "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/export.py"
    click Yaml "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/models/yolov5s.yaml"
    click CommonPY "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/models/common.py"
    click YoloPY "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/models/yolo.py"
    click TfPY "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/models/tf.py"
    click ExpPY "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/models/experimental.py"
    click Activations "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/activations.py"
    click Augmentations "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/augmentations.py"
    click Autoanchor "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/autoanchor.py"
    click Autobatch "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/autobatch.py"
    click Benchmarks "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/benchmarks.py"
    click Callbacks "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/callbacks.py"
    click Dataloaders "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/dataloaders.py"
    click Downloads "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/downloads.py"
    click General "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/general.py"
    click Loss "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/loss.py"
    click Metrics "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/metrics.py"
    click Plots "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/plots.py"
    click TorchUtils "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/utils/torch_utils.py"
    click CocoYAML "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/data/coco128.yaml"
    click DockerContainer "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/tree/master/Final_Project/API/Dockerfile"
    click DockerContainer "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/API/run.sh"
    click DockerContainer "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/tree/master/Final_Project/API/test/Dockerfile"
    click Yolov4NB "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/Source code/Yolov4_notebook.ipynb"
    click Yolov5NB "https://github.com/lynguyenminh/cs114.m11.vietnam-traffic-sign-detection/blob/master/Final_Project/Source code/Yolov5_notebook.ipynb"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#228B22,stroke-width:1px
    classDef ml fill:#FFE6B3,stroke:#FF8C00,stroke-width:1px
    classDef data fill:#FFF2B8,stroke:#DAA520,stroke-width:1px
    classDef offline fill:#E8E8E8,stroke:#A9A9A9,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666,stroke-width:1px
    class DockerContainer external
```
