# raianrashidrimon/butterfly-and-moth-detector architecture

> Architecture diagram of the GitHub repository raianrashidrimon/butterfly-and-moth-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raianrashidrimon/butterfly-and-moth-detector
- Repository: https://github.com/raianrashidrimon/butterfly-and-moth-detector

## Overview

1. **Project type and shape**
   - This is an **offline image-classification ML project**, not an app or service.
   - The repository is centered around one Python script, **`Butterfly & Moth Classification.py`**, with the rest of the repo providing the image dataset and documentation/visual outputs.

2. **Primary entrypoint**
   - The single Python file is the main orchestration point for the workflow.
   - It likely contains the full pipeline: load images, preprocess them, extract features, train a classifier, evaluate results, and display or save outputs.

3. **Dataset boundary**
   - Training data lives under **`Dataset/Butterly and Moth Images/`**.
   - Each subfolder is a **class label** named after a butterfly or moth species, so the directory structure itself encodes the target classes.
   - This is a supervised multiclass classification setup with many species folders rather than a flat label file.

4. **Data ingestion flow**
   - The script reads images from the class-named folders, building a list of samples and labels.
   - Because the repo contains only image folders and no separate annotation files, label assignment is inferred from folder names.
   - This makes the dataset boundary simple: **filesystem folder → image sample + class label**.

5. **Preprocessing subsystem**
   - The README explicitly says the pipeline uses **scikit-image** for:
     - reading images
     - resizing
     - grayscale conversion
     - HOG feature extraction
   - This means the model is not trained directly on raw pixels; instead, it uses a hand-engineered feature representation.

6. **Feature engineering and model input**
   - The core representation is likely **HOG (Histogram of Oriented Gradients)** descriptors computed from resized grayscale images.
   - That feature vector becomes the input to scikit-learn classifiers.
   - This creates a clear boundary between the image-processing layer and the ML layer: **image file → numeric feature vector → classifier**.

7. **Model training subsystem**
   - The README indicates use of **scikit-learn** for the model pipeline and grid search.
   - The training phase likely fits one or more classical ML classifiers on the extracted features rather than a deep-learning network.
   - Because grid search is mentioned, there is probably a hyperparameter-tuning step to improve accuracy.

8. **Evaluation subsystem**
   - Output artifacts in `Project Images/` include:
     - initial confusion matrix
     - improved confusion matrix
     - final console/IDLE output screenshot
   - This indicates iterative evaluation: the script produces a baseline result, then a tuned result, and compares performance visually using confusion matrices.

9. **Artifacts and documentation**
   - **`Project Images/`** stores screenshots/figures for the README, not runtime inputs.
   - These images document dataset size, example samples, the pipeline, and evaluation results.
   - There is no separate notebooks, API docs, or deployment config visible in the tree, reinforcing that this is a compact research/prototype repo.

10. **Persistence and reproducibility**
   - The README includes **joblib**, implying models and/or intermediate data may be serialized for reuse.
   - That suggests a simple offline persistence boundary: **trained model artifact saved locally → later reloaded for prediction or inspection**.

11. **External dependencies and runtime**
   - Required runtime is **Python 3.7+**.
   - Main libraries are:
     - **pandas** for tabular summaries
     - **matplotlib** for plots
     - **scikit-learn** for training, grid search, metrics
     - **scikit-image** for image preprocessing and HOG
     - **joblib** for serialization
   - These dependencies materially define the architecture: it is a classical ML pipeline with image-feature extraction, not a deep-learning stack.

12. **What to draw in an architecture diagram**
   - A clean diagram would show:
     - **Dataset folder hierarchy** on the left
     - **Single Python orchestration script** in the center
     - **Preprocessing/feature extraction** as the first processing stage
     - **Scikit-learn training/tuning/evaluation** as the ML stage
     - **Saved model / metrics / confusion matrix outputs** on the right
   - The key architectural boundary is between **raw image storage** and **numeric-feature-based classification**.

Main entry points: [`Butterfly & Moth Classification.py`](https://github.com/raianrashidrimon/butterfly-and-moth-detector/blob/HEAD/Butterfly%20%26%20Moth%20Classification.py) (Main script), [`Dataset/Butterly and Moth Images`](https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/HEAD/Dataset/Butterly%20and%20Moth%20Images) (Image dataset), [`README.md`](https://github.com/raianrashidrimon/butterfly-and-moth-detector/blob/main/README.md) (README), [`Project Images`](https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/HEAD/Project%20Images) (Confusion matrix)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_data["Data"]
  node_n_dataset_root[("Image dataset<br/>labeled image corpus")]
  node_n_class_dirs["Species folders<br/>class labels"]
  node_n_images["Raw images<br/>input samples"]
  node_n_readme["README<br/>documentation<br/>[README.md]"]
end

subgraph group_g_pipeline["Pipeline"]
  node_n_script["Main script<br/>python pipeline"]
  node_n_read_resize["Read resize<br/>preprocess"]
  node_n_gray["Grayscale<br/>preprocess"]
  node_n_hog["HOG features<br/>feature extractor"]
  node_n_feature_matrix[("Feature matrix<br/>numeric dataset")]
  node_n_train_split["Train split<br/>data split"]
  node_n_model["Classifier<br/>scikit-learn model"]
  node_n_grid["Grid search<br/>tuning"]
  node_n_eval["Evaluation<br/>metrics"]
end

subgraph group_g_outputs["Outputs"]
  node_n_cm["Confusion matrix<br/>result plot"]
  node_n_saved_model[("Saved model<br/>joblib artifact")]
  node_n_figures["Project images<br/>figures"]
end

node_n_dataset_root -->|"contains"| node_n_class_dirs
node_n_class_dirs -->|"organizes"| node_n_images
node_n_images -->|"feeds"| node_n_read_resize
node_n_read_resize -->|"normalize"| node_n_gray
node_n_gray -->|"describe"| node_n_hog
node_n_hog -->|"vectorize"| node_n_feature_matrix
node_n_feature_matrix -->|"split"| node_n_train_split
node_n_train_split -->|"fit"| node_n_model
node_n_model -->|"tune"| node_n_grid
node_n_grid -->|"validate"| node_n_eval
node_n_eval -->|"render"| node_n_cm
node_n_model -->|"serialize"| node_n_saved_model
node_n_script -->|"orchestrates"| node_n_read_resize
node_n_script -->|"orchestrates"| node_n_model
node_n_script -->|"orchestrates"| node_n_eval
node_n_readme -.->|"references"| node_n_figures

click node_n_script "https://github.com/raianrashidrimon/butterfly-and-moth-detector/blob/main/Butterfly & Moth Classification.py"
click node_n_dataset_root "https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/main/Dataset/Butterly and Moth Images"
click node_n_cm "https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/main/Project Images"
click node_n_readme "https://github.com/raianrashidrimon/butterfly-and-moth-detector/blob/main/README.md"
click node_n_figures "https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/main/Project Images"

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_n_dataset_root,node_n_class_dirs,node_n_images,node_n_readme toneBlue
class node_n_script,node_n_read_resize,node_n_gray,node_n_hog,node_n_feature_matrix,node_n_train_split,node_n_model,node_n_grid,node_n_eval toneAmber
class node_n_cm,node_n_saved_model,node_n_figures toneMint
```

## Components

### Data

Image classes and repo documentation assets

- [Image dataset](https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/HEAD/Dataset/Butterly%20and%20Moth%20Images): labeled image corpus · Class-per-folder butterfly and moth images used for supervised classification · `Dataset/Butterly and Moth Images`
- **Species folders**: class labels · Subfolders encode target species names for each image class
- **Raw images**: input samples · Per-class image files consumed by the pipeline
- [README](https://github.com/raianrashidrimon/butterfly-and-moth-detector/blob/main/README.md): documentation · Explains workflow, dependencies, and example outputs · `README.md`

### Pipeline

Single-script classical ML workflow

- [Main script](https://github.com/raianrashidrimon/butterfly-and-moth-detector/blob/HEAD/Butterfly%20%26%20Moth%20Classification.py): python pipeline · Orchestrates loading, preprocessing, feature extraction, training, and evaluation · `Butterfly & Moth Classification.py`
- **Read resize**: preprocess · Loads images and normalizes size before feature extraction
- **Grayscale**: preprocess · Converts images to grayscale for descriptor computation
- **HOG features**: feature extractor · Builds numeric descriptors from resized grayscale images
- **Feature matrix**: numeric dataset · Vectorized samples used as model input
- **Train split**: data split · Separates data for fitting and evaluation
- **Classifier**: scikit-learn model · Classical multiclass model trained on HOG features
- **Grid search**: tuning · Searches hyperparameters to improve classifier performance
- **Evaluation**: metrics · Computes predictions and performance summaries

### Outputs

Saved artifacts and visual results

- [Confusion matrix](https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/HEAD/Project%20Images): result plot · Visualizes baseline and improved classification outcomes · `Project Images`
- **Saved model**: joblib artifact · Serialized trained model for reuse or inspection
- [Project images](https://github.com/raianrashidrimon/butterfly-and-moth-detector/tree/HEAD/Project%20Images): figures · Screenshots and illustrative figures used in documentation · `Project Images`

## Connections

- Image dataset → Species folders: contains · Directory names define species labels
- Species folders → Raw images: organizes · Each class folder stores its image samples
- Raw images → Read resize: feeds · Raw image files are loaded from disk
- Read resize → Grayscale: normalize · Images are resized and converted to grayscale
- Grayscale → HOG features: describe · Hand-engineered descriptors are computed from normalized images
- HOG features → Feature matrix: vectorize · Per-image descriptors form the training matrix
- Feature matrix → Train split: split · Features are divided into train and evaluation sets
- Train split → Classifier: fit · Classifier is trained on labeled feature vectors
- Classifier → Grid search: tune · Hyperparameters are searched with grid search
- Grid search → Evaluation: validate · Best model is evaluated on held-out data
- Evaluation → Confusion matrix: render · Confusion matrices summarize performance
- Classifier → Saved model: serialize · Trained artifact can be saved with joblib
- Main script → Read resize: orchestrates · The single Python script drives preprocessing
- Main script → Classifier: orchestrates · The script coordinates model training
- Main script → Evaluation: orchestrates · The script produces evaluation output
- README → Project images: references · Documentation uses stored project figures