# kouz-1/moroccan_plates_detection architecture

> Architecture diagram of the GitHub repository kouz-1/moroccan_plates_detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kouz-1/moroccan_plates_detection
- Repository: https://github.com/kouz-1/moroccan_plates_detection

## Overview

##### Project Type and Purpose
- This is a standalone, end-to-end desktop application (Tkinter GUI) for Moroccan license-plate detection and recognition.
- It implements a sequential computer-vision/ML pipeline: input acquisition → plate detection (YOLOv5) → image preprocessing → character segmentation → character recognition (CNN) → result storage/display.

##### File Structure
Top-level files and folders:
- README.md, requirements.txt – project overview and dependencies
- gui.py, gui2.py – Tkinter GUI front ends
- char_model/char_model_1.h5 – trained CNN for character classification
- yolov5_model/best.pt – trained YOLOv5 model for plate detection
- process/ – core pipeline modules:
– main.py, main_char.py – orchestrators integrating all steps
– detect_char.py, segment_characters.py, find_contours.py – image-processing helpers
– predict_crop.py, save_plate_json.py, store_plate_to_mysql.py, check_plate_status.py, vehicle_manager.py – recognition, mapping to Latin, storage, and law-check
- cropped_plates/, json_plates/plates.json, predictions.txt – file-based I/O
- test_images/ – sample inputs

##### README for Technical Stack and Pipeline
- Python + OpenCV for image handling
- YOLOv5 (PyTorch) for object detection
- TensorFlow/Keras for CNN character recognition
- MySQL for status checks
- Tkinter for GUI

##### Main Components
A. User Interface Layer (GUI)
- Modules: gui.py / gui2.py (Tkinter)
- Functions: Load Image/Video/Camera, Start Detection, Check Status, Exit
B. Input Sources
- Static image files, video files, webcam stream
C. Plate Detection Service
- YOLOv5 Model (yolov5_model/best.pt) loaded by detect_plate module
- Output: cropped plate images → saved to cropped_plates/
D. Preprocessing and Segmentation
- Preprocessor (grayscale, resize, denoise)
- Contour-based segmentation (find_contours.py) → individual character crops
E. Character Recognition Service
- CNN model (char_model_1.h5) loaded by predict_crop.py
- Maps Arabic → Latin (via vehicle_manager.py/ JSON mapping)
- Produces plate string (e.g., “82227-A-6”)
F. Business Logic / Status Check
- store_plate_to_mysql.py: store detected plate in MySQL
- check_plate_status.py: query database to flag violations
G. Output and Storage
- JSON output (json_plates/plates.json)
- predictions.txt (flat-file log)
- GUI display of results and status

##### Relationships and Data Flow
- GUI triggers the Pipeline Orchestrator (main.py or main_char.py)
- Orchestrator calls Plate Detection → yields cropped images
- Cropped images feed into Preprocessing & Segmentation → character images
- Character images passed to CNN for recognition → returns character labels
- Recognized plate string sent to Vehicle Manager for mapping & status check
- Results flow back to GUI for display and to storage modules (JSON, MySQL, flat files)

##### Architectural Patterns and Principles
- Layered architecture: UI → Application Logic → ML Services → Persistence
- Single-process, modular design: each .py file encapsulates a distinct step
- Clear separation of concerns: detection, segmentation, recognition, storage
- Extensibility points: swap models (YOLOv5, char CNN), change storage back ends

d. To “Preprocessor” → “Segmenter” → “CNN Char Recognizer”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface (Tkinter)" 
        direction TB
        GUI1["gui.py"]:::ui
        GUI2["gui2.py"]:::ui
    end

    %% Input Sources
    TestImages["test_images/"]:::processing

    %% Pipeline Orchestrator
    subgraph "Orchestrator" 
        direction TB
        MainApp["process/main.py"]:::processing
        MainChar["process/main_char.py"]:::processing
    end

    %% Plate Detection Service
    subgraph "Plate Detection (YOLOv5)" 
        direction TB
        Detect["process/detect_char.py"]:::processing
        YOLOModel["best.pt"]:::model
    end

    %% Preprocessing & Contour Detection
    Preprocess["process/find_contours.py"]:::processing

    %% Character Segmentation
    Segment["process/segment_characters.py"]:::processing

    %% Character Recognition Service
    subgraph "Recognition (CNN)" 
        direction TB
        Predict["process/predict_crop.py"]:::processing
        CharModel["char_model/char_model_1.h5"]:::model
    end

    %% Vehicle Mapping & Status Check
    VehicleMgr["process/vehicle_manager.py"]:::processing

    %% JSON Output Storage
    subgraph "JSON Output" 
        direction TB
        SaveJSON["process/save_plate_json.py"]:::storage
        JSONFile["json_plates/plates.json"]:::storage
    end

    %% Flat-File Logging
    LogFile["predictions.txt"]:::storage

    %% MySQL Persistence
    subgraph "MySQL Persistence" 
        direction TB
        StoreMySQL["process/store_plate_to_mysql.py"]:::storage
        CheckStatus["process/check_plate_status.py"]:::storage
        MySQLDB[(MySQL DB)]:::storage
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        OpenCV["OpenCV"]:::external
        PyTorch["PyTorch"]:::external
        TensorFlow["TensorFlow"]:::external
        MySQLExt["MySQL Driver"]:::external
    end

    %% Connections
    GUI1 -->|"select image/video/camera"| TestImages
    GUI2 -->|"select image/video/camera"| TestImages

    TestImages -->|"input image stream"| MainApp
    MainChar --> MainApp
    MainApp -->|"call detection"| Detect
    Detect -->|"uses model"| YOLOModel
    Detect -->|"cropped plates"| Preprocess
    Preprocess -->|"contours"| Segment
    Segment -->|"character images"| Predict
    Predict -->|"uses model"| CharModel
    Predict -->|"plate string"| VehicleMgr

    VehicleMgr -->|"plate record"| StoreMySQL
    StoreMySQL --> MySQLDB
    VehicleMgr -->|"check violations"| CheckStatus
    CheckStatus --> MySQLDB
    VehicleMgr -->|"mapped string"| SaveJSON
    SaveJSON --> JSONFile
    VehicleMgr -->|"mapped string"| LogFile

    MySQLDB -->|"status info"| GUI1
    MySQLDB -->|"status info"| GUI2
    JSONFile -->|"json output"| GUI1
    JSONFile -->|"json output"| GUI2
    LogFile -->|"log update"| GUI1
    LogFile -->|"log update"| GUI2

    %% Dependencies arrows
    Detect --> OpenCV
    Detect --> PyTorch
    Preprocess --> OpenCV
    Segment --> OpenCV
    Predict --> TensorFlow
    StoreMySQL --> MySQLExt
    CheckStatus --> MySQLExt

    %% Click Events
    click GUI1 "https://github.com/kouz-1/moroccan_plates_detection/blob/main/gui.py"
    click GUI2 "https://github.com/kouz-1/moroccan_plates_detection/blob/main/gui2.py"
    click TestImages "https://github.com/kouz-1/moroccan_plates_detection/tree/main/test_images/"
    click MainApp "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/main.py"
    click MainChar "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/main_char.py"
    click Detect "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/detect_char.py"
    click YOLOModel "https://github.com/kouz-1/moroccan_plates_detection/blob/main/yolov5_model/best.pt"
    click Preprocess "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/find_contours.py"
    click Segment "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/segment_characters.py"
    click Predict "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/predict_crop.py"
    click CharModel "https://github.com/kouz-1/moroccan_plates_detection/blob/main/char_model/char_model_1.h5"
    click VehicleMgr "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/vehicle_manager.py"
    click SaveJSON "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/save_plate_json.py"
    click JSONFile "https://github.com/kouz-1/moroccan_plates_detection/blob/main/json_plates/plates.json"
    click LogFile "https://github.com/kouz-1/moroccan_plates_detection/blob/main/predictions.txt"
    click StoreMySQL "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/store_plate_to_mysql.py"
    click CheckStatus "https://github.com/kouz-1/moroccan_plates_detection/blob/main/process/check_plate_status.py"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef model fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef external fill:#F0E68C,stroke:#333,stroke-width:1px;
```
