🧠Containerized Real-Time ML Inference Service

A full-stack machine learning application that classifies handwritten digits (0-9) using a neural network trained on the MNIST dataset. Features a modern React frontend with canvas drawing, a robust FastAPI backend, and complete Docker containerization.

🎯 Project Overview

This project demonstrates an end-to-end machine learning deployment pipeline:

• Neural Network: Trained on the MNIST dataset (60,000 training images) achieving ~98% accuracy.
• Interactive Frontend: React-based UI allowing users to draw digits directly in the browser.
• Real-time Inference: FastAPI backend that processes images and serves predictions instantly.
• Production Ready: Fully containerized with Docker and Nginx for easy deployment.

🏗️ Architecture

graph LR
    User[User] -->|Draws Digit| Frontend[React Frontend :3000]
    Frontend -->|POST /predict| Backend[FastAPI Backend :8000]
    Backend -->|Preprocess| Processor[Image Processor]
    Processor -->|Inference| Model[TensorFlow Model]
    Model -->|Probabilities| Backend
    Backend -->|JSON Response| Frontend

Loading

🚀 Quick Start

Option 1: Using Docker (Recommended)

The easiest way to run the application is using Docker Compose.

1. Clone the repository:

   git clone <repository-url>
   cd neural-network-project

2. Start the application:

   docker-compose up --build

3. Access the application:

   • 🎨 Frontend: http://localhost:3000
   • 🔌 Backend API: http://localhost:8000/docs (Swagger UI)
   • 💓 Health Check: http://localhost:8000/health

4. Stop the application:

   docker-compose down

Option 2: Local Development

Backend Setup

1. Create and activate a virtual environment (Python 3.11+).
2. Install dependencies:

   cd backend
   pip install -r requirements.txt

3. Run the server:

   uvicorn predict:app --reload

Frontend Setup

1. Install dependencies:

   cd frontend
   npm install

2. Start the dev server:

   npm run dev

🧠 Model & Preprocessing

Model Architecture

The model is a feedforward neural network built with Keras:

• Input: 784 neurons (flattened 28x28 image)
• Hidden Layer 1: 128 neurons (ReLU)
• Hidden Layer 2: 64 neurons (ReLU)
• Output: 10 neurons (Softmax)

Smart Preprocessing Pipeline

To ensure the model works with user drawings, the backend implements a robust preprocessing pipeline that mimics the MNIST dataset preparation:

1. Grayscale Conversion: Converts input to single channel.
2. Auto-Cropping: Detects the digit's bounding box and crops empty whitespace.
3. Centering & Padding: Centers the digit on a 28x28 canvas with 20% padding.
4. Inversion: Inverts colors (Canvas is black-on-white, MNIST is white-on-black).
5. Normalization: Scales pixel values to [0, 1].

📂 Project Structure

neural-network-project/
├── backend/
│   ├── predict.py              # FastAPI application & logic
│   ├── requirements.txt        # Python dependencies
│   ├── Dockerfile              # Backend container config
│   └── .dockerignore
├── frontend/
│   ├── src/
│   │   ├── App.jsx             # Main React component
│   │   └── ...
│   ├── package.json            # Node dependencies
│   ├── Dockerfile              # Frontend container config
│   ├── nginx.conf              # Nginx configuration for serving React
│   └── vite.config.js          # Vite build config
├── Model_v1/
│   └── my_model.keras          # Trained TensorFlow model
├── Neural_Network_Project.ipynb # Jupyter notebook for training
├── docker-compose.yml          # Orchestration config
└── README.md

🔧 API Reference

POST /predict

Uploads an image file for digit classification.

Request: multipart/form-data

• file: The image file (PNG/JPEG)

Response:

{
  "predicted_digit": 7,
  "confidence": 0.985,
  "probabilities": [0.001, 0.000, ..., 0.985, ..., 0.002]
}

🐛 Troubleshooting

"Model not found" error: Ensure the Model_v1 directory contains my_model.keras. If running locally, make sure you are in the correct directory.

"Port already in use": Stop any running containers (docker ps -> docker stop <id>) or change ports in docker-compose.yml.

Accuracy issues: Try drawing the digit larger and in the center. The preprocessing handles most cases, but very thin lines or tiny drawings might be harder to recognize.

🔮 Future Improvements

• Add Convolutional Neural Network (CNN) for better accuracy.
• Implement user feedback loop to save misclassified images for retraining.
• Add support for mobile touch drawing.

📄 License

This project is for educational purposes. The MNIST dataset is publicly available and free to use.

📧 Contact

Author: Ogheneobukome Ejaife

---

🚀 Quick Start Commands

# 1. Create environment
conda create -n tensorflow-env python=3.11 -y && conda activate tensorflow-env

# 2. Install dependencies
pip install tensorflow scikit-learn numpy matplotlib jupyter ipykernel

# 3. Run notebook
code Neural_Network_Project.ipynb

# 4. Select tensorflow-env kernel in VS Code and run all cells!

Happy Learning! 🎉 This project is open source and available under the MIT License.