🤖 ML Image Classifier Web App

A full-stack web application demonstrating ML model deployment and inference with built-in explainability using Grad-CAM visualization.

🌟 Features

• Image Classification: Upload images and get AI-powered object classification using MobileNetV2 (ImageNet)
• Model Explainability: Built-in Grad-CAM (Gradient-weighted Class Activation Mapping) visualization showing which parts of the image influenced the model's decision
• Modern UI: Responsive React frontend with drag-and-drop image upload
• Production-Ready: FastAPI backend optimized for performance
• Cloud Deployment: One-command deployment to Google Cloud Run
• Docker Support: Containerized application for easy local development and deployment

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        React Frontend                        │
│  - Image Upload UI (Drag & Drop)                            │
│  - Results Display                                           │
│  - Grad-CAM Visualization Toggle                            │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTP/REST API
┌─────────────────────▼───────────────────────────────────────┐
│                      FastAPI Backend                         │
│  - /predict endpoint                                         │
│  - Image preprocessing                                       │
│  - Model inference                                           │
│  - Grad-CAM generation                                       │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   TensorFlow/Keras                           │
│  - MobileNetV2 (ImageNet pretrained)                        │
│  - 1000 object classes                                       │
│  - Gradient computation for Grad-CAM                        │
└─────────────────────────────────────────────────────────────┘

📋 Prerequisites

• Python 3.10+
• Node.js 18+
• Docker (optional, for containerized deployment)
• Google Cloud SDK (optional, for Cloud Run deployment)

🚀 Quick Start

Option 1: Local Development (Separate Backend/Frontend)

Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the FastAPI server
python main.py

The backend will be available at http://localhost:8000

API Documentation: http://localhost:8000/docs

Frontend Setup

# In a new terminal, navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start the development server
npm run dev

The frontend will be available at http://localhost:3000

Option 2: Docker Compose (Recommended)

# Start both backend and frontend with one command
docker-compose up

# Or run in detached mode
docker-compose up -d

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080
• API Docs: http://localhost:8080/docs

📁 Project Structure

AI-Image-Classifier-App/
├── backend/
│   ├── main.py              # FastAPI application
│   ├── model_handler.py     # Model loading and inference
│   ├── gradcam.py          # Grad-CAM implementation
│   └── requirements.txt     # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ImageUploader.jsx
│   │   │   ├── ResultsDisplay.jsx
│   │   │   └── *.css
│   │   ├── App.jsx
│   │   ├── main.jsx
│   │   └── index.css
│   ├── package.json
│   └── vite.config.js
├── models/                  # Directory for custom models
├── Dockerfile              # Production Docker image
├── docker-compose.yml      # Local development setup
├── deploy.sh              # Cloud Run deployment script
└── README.md

🔌 API Endpoints

GET /

Health check endpoint

{
  "status": "healthy",
  "service": "ML Image Classifier",
  "version": "1.0.0"
}

GET /health

Detailed health check with model status

{
  "status": "healthy",
  "model_loaded": true,
  "model_info": {...}
}

POST /predict

Classify an uploaded image

Request: multipart/form-data with image file

Response:

{
  "success": true,
  "predictions": [
    {
      "class_idx": 123,
      "class_name": "golden_retriever",
      "confidence": 0.89,
      "confidence_percent": "89.00%"
    },
    ...
  ],
  "original_image": "data:image/png;base64,...",
  "gradcam_image": "data:image/png;base64,...",
  "top_prediction": {...}
}

GET /classes

Get list of all available classification classes

🎨 Grad-CAM Explainability

Grad-CAM (Gradient-weighted Class Activation Mapping) is a technique for making visual explanations from CNN-based models. It highlights the regions in the image that were most important for the model's prediction.

How it works:

1. Computes the gradient of the predicted class score with respect to the final convolutional layer
2. Pools the gradients to get feature importance weights
3. Creates a heatmap by weighting the feature maps
4. Overlays the heatmap on the original image

Interpretation:

• Red/Yellow regions: High importance (model focused here)
• Blue/Purple regions: Low importance
• Green regions: Medium importance

☁️ Cloud Deployment (Google Cloud Run)

Prerequisites

1. Install Google Cloud SDK
2. Authenticate: gcloud auth login
3. Set your project: gcloud config set project YOUR_PROJECT_ID

Deploy

# Set environment variables
export GCP_PROJECT_ID="your-project-id"
export GCP_REGION="us-central1"  # Optional, defaults to us-central1

# Run deployment script
./deploy.sh

The script will:

1. Build the Docker image
2. Push to Google Container Registry
3. Deploy to Cloud Run
4. Output the public URL

Manual Deployment

# Build and tag image
docker build -t gcr.io/YOUR_PROJECT_ID/ml-image-classifier .

# Push to GCR
docker push gcr.io/YOUR_PROJECT_ID/ml-image-classifier

# Deploy to Cloud Run
gcloud run deploy ml-image-classifier \
  --image gcr.io/YOUR_PROJECT_ID/ml-image-classifier \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 2Gi \
  --cpu 2

🧪 Testing the Application

Using cURL

# Health check
curl http://localhost:8000/health

# Predict with image
curl -X POST \
  http://localhost:8000/predict \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/image.jpg'

Using Python

import requests

# Upload and classify image
with open('image.jpg', 'rb') as f:
    files = {'file': f}
    response = requests.post('http://localhost:8000/predict', files=files)
    result = response.json()

print(f"Top prediction: {result['top_prediction']['class_name']}")
print(f"Confidence: {result['top_prediction']['confidence_percent']}")

🔧 Customization

Using Your Own Model

1. Save your Keras/TensorFlow model to the models/ directory
2. Update model_handler.py:

def __init__(self, model_path: str = "models/your_model.h5"):
    self.model_path = model_path
    # ... rest of the code

3. Update class labels if needed:

self.classes = ["class1", "class2", "class3", ...]

Adjusting Grad-CAM Settings

In gradcam.py, modify the generate() method:

# Change overlay transparency (0.0 - 1.0)
def generate(self, image: Image.Image, class_idx: int, alpha: float = 0.4):
    # Lower alpha = more transparent heatmap
    # Higher alpha = more opaque heatmap

🐛 Troubleshooting

Backend Issues

Model loading errors:

# Check TensorFlow installation
python -c "import tensorflow as tf; print(tf.__version__)"

# Re-install TensorFlow
pip uninstall tensorflow
pip install tensorflow==2.15.0

Port already in use:

# Kill process on port 8000
lsof -ti:8000 | xargs kill -9

# Or use a different port
uvicorn backend.main:app --port 8001

Frontend Issues

Build errors:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

API connection issues:

• Check CORS settings in backend/main.py
• Verify VITE_API_URL in .env or vite.config.js

📊 Performance Considerations

• Model: MobileNetV2 is optimized for inference speed (~30-50ms per image)
• Memory: ~500MB for model + gradients
• Scaling: Cloud Run auto-scales based on traffic
• Optimization: Consider TensorFlow Lite for edge deployment

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• MobileNetV2: Pre-trained model from TensorFlow/Keras
• Grad-CAM: Original paper by Selvaraju et al. (2017)
• FastAPI: Modern, fast web framework for building APIs
• React: UI library for building interactive interfaces

📚 Resources

• FastAPI Documentation
• TensorFlow Guide
• Grad-CAM Paper
• Google Cloud Run Docs

📞 Support

For issues, questions, or suggestions, please open an issue on GitHub.

---

Built with ❤️ using FastAPI, TensorFlow, and React