# raaghavagarwal28/fashion-mnist architecture

> Architecture diagram of the GitHub repository raaghavagarwal28/fashion-mnist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raaghavagarwal28/fashion-mnist
- Repository: https://github.com/raaghavagarwal28/fashion-mnist

## Overview

##### Project Type and Purpose
- This is a machine-learning research/demo pipeline contained in a Jupyter notebook (with a companion Python script).
- Purpose: train and evaluate a CNN on Fashion-MNIST, produce Grad-CAM visualizations, quantitatively evaluate with a “Pointing Game,” and generate natural-language explanations via Google Gemini LLM.

##### File Structure
- Top level:
- Another_copy_of_LuvByte.ipynb (the orchestrating notebook)
- another_copy_of_luvbyte.py (script version of the same pipeline)
- README.md
- No traditional frontend/backend split or service directories—this is a single‐process ML pipeline.

##### Key Architectural Insights from the README
- Pipeline stages are implemented sequentially in code cells/functions.
- External dependency: Google Gemini API (for LLM explanations).
- Core technologies: TensorFlow/Keras, tf-keras-vis (Grad-CAM), OpenCV, scikit-learn, Matplotlib/Seaborn, Pillow, google-generativeai.

##### Main Components & Their Interactions
a. Data Ingestion & Preprocessing Module
- Load Fashion-MNIST from Keras datasets
- Normalize pixel values, reshape to (28,28,1)
b. Model Definition & Training Module
- CNN with Conv2D, BatchNorm, MaxPooling, GlobalAveragePooling2D, Dense, Dropout
- Compile and train with early stopping
c. Evaluation Module
- Compute test accuracy and macro-F1Score
- Generate confusion matrix plots
- Run “Pointing Game” quantitative evaluation on Grad-CAM localizations
d. Grad-CAM Visualization Module
- Use tf-keras-vis to overlay heatmaps on input images
- Produce visual outputs for each test/custom image
e. LLM Explanation Module
- Send Grad-CAM outputs (e.g., heatmap statistics, key pixel location) to Google Gemini API
- Receive and render natural-language explanation
f. Custom Image Prediction Pipeline
- Accept user image (via notebook file upload cell)
- Preprocess, run through trained CNN, Grad-CAM, and LLM modules
- Prediction, heatmap overlay, and textual explanation

##### Architectural Patterns & Design Principles
- Linear data-processing pipeline (ETL-style with distinct stages)
- Modular code cells/functions that can be extracted into standalone scripts
- Separation of concerns: model training vs. interpretability vs. LLM integration

- Beneath it, arrange modules left to right in execution order:
1. Data Ingestion & Preprocessing
2. Model Definition & Training
3. Evaluation (Accuracy, F1, Confusion Matrix, Pointing Game)
4. Grad-CAM Visualization
5. LLM Explanation (External Service: Google Gemini API)
6. Custom Image Prediction Pipeline
- Raw dataset → Preprocessing → Trained Model
- Trained Model + Test Images → Evaluation & Grad-CAM
- Grad-CAM Outputs → Pointing Game & LLM API → Explanations
- Custom Image Input → entire pipeline

##### Detail
- Every functional block from the notebook is represented.
- Both quantitative evaluation (Pointing Game) and qualitative explanation (Gemini LLM).
- Don’t forget the user-uploaded custom image flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestrator
    Notebook["Notebook Orchestrator"]:::orchestrator
    Script["Script Orchestrator"]:::orchestrator
    Notebook -->|runs pipeline| DataIngestion
    Script -->|runs pipeline| DataIngestion

    %% Data Stage
    Dataset[(Fashion-MNIST Dataset)]:::data
    DataIngestion["Data Ingestion & Preprocessing\n(TensorFlow/Keras)"]:::data
    Dataset -->|raw images| DataIngestion

    %% Model Stage
    ModelTrain["Model Definition & Training\n(TensorFlow/Keras)"]:::model
    DataIngestion -->|preprocessed images| ModelTrain

    %% Parallel Evaluation and Interpretability
    subgraph Evaluation & Interpretability
        direction TB
        Eval["Evaluation\n(Accuracy, F1, Confusion Matrix)\n(scikit-learn, Matplotlib)"]:::model
        GradCam["Grad-CAM Visualization\n(tf-keras-vis, OpenCV)"]:::interpret
        Eval
        GradCam
    end
    ModelTrain -->|trained model| Eval
    ModelTrain -->|trained model| GradCam
    DataIngestion -->|test images| Eval
    DataIngestion -->|test images| GradCam

    %% Pointing Game metrics branch
    GradCam -->|heatmap metrics| Eval

    %% LLM Explanation
    LLM["LLM Explanation\n(google-generativeai)"]:::external
    GradCam -->|heatmap stats| LLM
    LLM -->|textual explanations| Notebook
    LLM -->|textual explanations| Script

    %% Custom Image Prediction Pipeline
    CustomPred(("Custom Image Input")):::data
    CustomPred -->|upload image| DataIngestion
    DataIngestion -->|preprocessed image| ModelTrain
    ModelTrain -->|prediction| GradCam
    GradCam -->|heatmap metrics| LLM
    LLM -->|explanation| CustomPred

    %% External Services
    API{{"Google Gemini API"}}:::external
    LLM -->|API request/response| API

    %% Click Events
    click Notebook "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/Another_copy_of_LuvByte.ipynb"
    click Script "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/another_copy_of_luvbyte.py"
    click DataIngestion "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/Another_copy_of_LuvByte.ipynb"
    click ModelTrain "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/Another_copy_of_LuvByte.ipynb"
    click Eval "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/Another_copy_of_LuvByte.ipynb"
    click GradCam "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/Another_copy_of_LuvByte.ipynb"
    click LLM "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/Another_copy_of_LuvByte.ipynb"
    click CustomPred "https://github.com/raaghavagarwal28/fashion-mnist/blob/main/Another_copy_of_LuvByte.ipynb"

    %% Styles
    classDef data fill:#D0E7FF,stroke:#0066CC,color:#003366
    classDef model fill:#DFFFD0,stroke:#669900,color:#336600
    classDef interpret fill:#FFE7C0,stroke:#FF9900,color:#CC6600
    classDef external fill:#F0D0FF,stroke:#9900CC,color:#660066
    classDef orchestrator fill:#F0F0F0,stroke:#666666,color:#333333
```
