README.md

metadata

title: Image Classifier With CNN
emoji: 🚀
colorFrom: red
colorTo: red
sdk: docker
app_port: 8501
tags:
  - streamlit
pinned: true
short_description: A CNN-based image classification with TensorFlow
license: mit

🖼️ Image Classification with ResNet50

Table of Contents

1. Project Description
2. Methodology & Key Features
3. Technology Stack
4. Deployment Options
5. Model

1. Project Description

This project implements an image classification system using a pre-trained ResNet50 CNN (trained on ImageNet with 1,000+ categories).

The repository includes two versions:

1. Full Architecture (local, Dockerized):

   • Built as a multi-service ML system with FastAPI (backend inference), Redis (queue/cache), and Streamlit (frontend).
   • Designed to demonstrate a scalable, production-like workflow.

2. Lightweight Streamlit App (deployed):

   • Adapted into a single Streamlit app for cost-effective deployment on Hugging Face Spaces.
   • Lets users upload an image and instantly see the predicted category with confidence.

This dual approach allows others to explore both a realistic ML architecture and a lightweight, deployable demo.

• Check out the deployed app here: 👉️ Image Classification App 👈️
• Check out the source code for multi-service setup: 👉️ Multi-Service - Source Code 👈️
• Check out the source code for lightweight Streamlit App: 👉️ Lightweight App - Source Code 👈️

2. Methodology & Key Features

• Model: ResNet50 (pre-trained on ImageNet with 1,000+ classes).
• Pipeline: Input images are resized, normalized, and passed to the model.
• Output: Top-1 prediction with confidence score is displayed.
• Multi-service architecture:
  • FastAPI serves inference requests.
  • Redis handles caching and task queueing.
  • Streamlit provides the interactive UI.
• Lightweight deployment: Direct Streamlit-only version for Hugging Face Spaces.

3. Technology Stack

This project was built using the following technologies:

Deployment & Hosting:

• Docker – containerization for the full architecture.
• Hugging Face Spaces – for lightweight deployment.
• Streamlit – interactive web app frontend.

Backend & Infrastructure:

• FastAPI – high-performance inference API.
• Redis – caching and message queue.

Modeling & Training:

• TensorFlow / Keras – ResNet50 model (pre-trained on ImageNet).

Development Tools:

• Ruff – Python linter and formatter.
• uv – fast Python package installer and resolver.

4. Deployment Options

You can run this project in two ways:

A. Run the Lightweight Version (Streamlit-only)

1. Clone the repo:

   git clone https://huggingface.co/spaces/iBrokeTheCode/Image_Classifier_with_CNN
   
   cd Image_Classifier_with_CNN
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Run the app:

   streamlit run src/streamlit_app.py
   

B. Run the Full Architecture (Dockerized)

The repository also contains Dockerfiles for each service.

1. Clone the repo:

    git clone https://huggingface.co/spaces/iBrokeTheCode/Image_Classifier_with_CNN
   
   cd Image_Classifier_with_CNN
   

2. Pre-configure your environment variables:

   cp .env.original .env
   

3. Create a network for containers

   docker network create shared_network
   

4. Build and start all services:

   docker compose up --build -d
   
   # Stop services
   docker compose down
   

5. Populate the database

   cd api
   cp .env.original .env
   docker-compose up --build -d
   

6. Access the app at:

   http://localhost:9090
   

   Then use this credentials to pass the login:

   • Username: admin@example.com
   • Password: admin

7. Access the FastAPI app at:

   http://localhost:8000/docs
   

5. Model

This project uses the pre-training model ResNet50.

• Model: ResNet50
• Classes: 1,000+ categories (objects, animals, everyday items).