# gamal1osama/garbage-classifier architecture

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

- Interactive diagram: https://gitdiagram.com/gamal1osama/garbage-classifier
- Repository: https://github.com/gamal1osama/garbage-classifier

## Overview

##### Project Type and Purpose
- This is a full-stack ML application for real-time image classification of garbage into ten categories.
- It combines a web-based UI (Gradio) with backend inference logic (Python + TensorFlow) and two interchangeable model architectures (custom CNN and fine-tuned ResNet-101v2).

##### File Structure
- Top-level:
- .gradio/           → Gradio SSL certificates and UI config
- CNN/               → Jupyter notebook and training artifacts for the custom CNN
- Resnet_101v2/      → Jupyter notebook, model file (.keras), and training history for ResNet-101v2
- Deployment/app.py  → Main application entrypoint running the Gradio interface and inference logic
- requirements.txt   → Python dependencies
- Pattern: Monolithic service with pluggable model submodules, served via a single Gradio app.

##### README for Additional Insights
- Key technologies: Python 3.8+, TensorFlow 2.8+, Gradio 3.x
- Two ML pipelines (CNN vs. ResNet-101v2) selectable at runtime
- Real-time image processing and classification with disposal recommendations
- Live deployment on Hugging Face Spaces

a. Components:
1. Client UI (Web Browser)
2. Gradio Frontend
3. app.py Backend Controller
4. Model Manager (loads either CNN or ResNet)
5. TensorFlow Inference Engine
6. Model Artifacts Storage (./CNN/details, ./Resnet_101v2/)
7. Disposal Recommendation Module (simple rules triggered by classification)
8. External Demo Host (Hugging Face Space) – optional external endpoint
b. Interactions:
- Browser → Gradio Frontend: Upload image & select model
- Gradio Frontend → app.py: REST / WebSocket call
- app.py → Model Manager: load selected model if not in memory
- Model Manager → Model Artifacts Storage: read .keras or serialized weights
- Model Manager → TensorFlow: perform inference
- TensorFlow → app.py: return class probabilities
- app.py → Disposal Module: map class to disposal instructions
- app.py → Gradio Frontend: send back results and recommendations
- Gradio Frontend → Browser: render classification and advice
- (Optional) app.py → Hugging Face API for metrics/event logging
c. Architectural Patterns & Principles:
- Single-process, pluggable modules (strategy pattern for model selection)
- Clear separation: UI (view), app.py (controller), model artifacts (data)
- Use of dependency files (requirements.txt) for reproducibility
d. Key Technologies:
- Python with Gradio for UI
- TensorFlow/Keras for model inference
- Jupyter Notebooks for experimentation (CNN/ResNet)
- File-based model storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        Browser["Web Browser"]:::ui
        Gradio["Gradio Frontend"]:::ui
    end

    %% UI Config Files
    subgraph "UI Configuration"
        GradioConfig[".gradio/"]:::config
        Cert["certificate.pem"]:::config
    end

    Browser -->|"Upload Image & Select Model"| Gradio
    Gradio --> GradioConfig
    GradioConfig --> Cert

    %% Backend Layer
    subgraph "Backend"
        App["app.py\n(Controller)"]:::backend
        ModelManager["Model Manager\n(Strategy Pattern)"]:::backend
        TensorFlow["TensorFlow\nInference Engine"]:::backend
        Disposal["Disposal Recommendation\nModule"]:::backend
    end

    Gradio -->|"REST/WebSocket"| App
    App -->|"load selected model"| ModelManager
    ModelManager -->|"read model files"| ModelStorage
    ModelManager -->|"run inference"| TensorFlow
    TensorFlow -->|"class probabilities"| App
    App -->|"map class to advice"| Disposal
    Disposal -->|"recommendation"| App
    App --> Gradio

    %% Model Artifacts Storage
    subgraph "Model Artifacts Storage"
        direction TB
        subgraph "CNN Pipeline"
            CNNDir["Custom CNN Directory"]:::data
            CNNNB["garbage-classification.ipynb"]:::data
            CNNArt["CNN/details/"]:::data
        end
        subgraph "ResNet Pipeline"
            ResDir["ResNet_101v2 Directory"]:::data
            ResNB["garbage-classification-f1-96-resnet-101v2.ipynb"]:::data
            ResModel["finetuned_garbage_classifier_model_ResNet101V2.keras"]:::data
            ResArt["Resnet_101v2/details/"]:::data
        end
    end

    ModelStorage --> CNNDir
    ModelStorage --> ResDir

    %% External Services
    subgraph "External Services"
        HuggingFace["Hugging Face Spaces API"]:::external
    end

    App -->|"optional metrics logging"| HuggingFace

    %% Configuration Dependency
    requirements["requirements.txt"]:::config
    App --> requirements

    %% Click Events
    click GradioConfig "https://github.com/gamal1osama/garbage-classifier/tree/main/.gradio/"
    click Cert "https://github.com/gamal1osama/garbage-classifier/blob/main/.gradio/certificate.pem"
    click App "https://github.com/gamal1osama/garbage-classifier/blob/main/Deployment/app.py"
    click CNNDir "https://github.com/gamal1osama/garbage-classifier/tree/main/CNN/"
    click CNNNB "https://github.com/gamal1osama/garbage-classifier/blob/main/CNN/garbage-classification.ipynb"
    click CNNArt "https://github.com/gamal1osama/garbage-classifier/tree/main/CNN/details/"
    click ResDir "https://github.com/gamal1osama/garbage-classifier/tree/main/Resnet_101v2/"
    click ResNB "https://github.com/gamal1osama/garbage-classifier/blob/main/Resnet_101v2/garbage-classification-f1-96-resnet-101v2.ipynb"
    click ResModel "https://github.com/gamal1osama/garbage-classifier/blob/main/Resnet_101v2/finetuned_garbage_classifier_model_ResNet101V2.keras"
    click ResArt "https://github.com/gamal1osama/garbage-classifier/tree/main/Resnet_101v2/details/"
    click requirements "https://github.com/gamal1osama/garbage-classifier/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef backend fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef data fill:#FFF9C4,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef config fill:#FFE0B2,stroke:#333,stroke-width:1px
```
