Brain Tumor Classification

A full-stack deep learning application for classifying brain tumors from MRI scans.
Built with EfficientNetB1, FastAPI, and React.

Classes	Glioma · Meningioma · Pituitary · No Tumor
Architecture	EfficientNetB1 (transfer learning, ImageNet weights)
Input	224 × 224 RGB MRI image
License	CC0 1.0 Universal

---

Tech Stack

Layer	Technology	Purpose
Deep Learning		Model training, inference, and EfficientNetB1 backbone
Computer Vision		Image preprocessing (resize, color conversion, normalization)
Backend API		REST API, request validation, static file serving
Frontend		Single-page application with drag-and-drop upload
Containerization		Multi-stage build for production deployment
Language		Backend logic and frontend interactivity

---

Project Structure

Brain-Tumor-Classification/
|
|-- app/
|   |-- client/                   # React frontend (Vite + Tailwind CSS)
|   |   |-- src/
|   |   |   |-- components/       # Navbar, UploadBox, ResultCard, ConfidenceChart, etc.
|   |   |   |-- services/api.js   # API client (calls /api/predict)
|   |   |   |-- App.jsx           # Root component
|   |   |   |-- index.css         # Global styles
|   |   |-- package.json
|   |   |-- vite.config.js
|   |
|   |-- server/
|       |-- api/
|       |   |-- api.py            # FastAPI application, routes, and SPA serving
|       |-- backend/
|           |-- model.py          # Model loader (reads MODEL_PATH from env)
|           |-- predict.py        # Predictor class (preprocess + inference)
|
|-- model/                        # Training pipeline (not shipped in Docker)
|   |-- config.py                 # Hyperparameters and file paths
|   |-- data.py                   # Dataset loading via image_dataset_from_directory
|   |-- preprocess.py             # Training-time preprocessing
|   |-- model.py                  # EfficientNetB1 architecture definition
|   |-- train.py                  # Training loop with callbacks
|   |-- evaluate.py               # Evaluation metrics and confusion matrix
|   |-- main.py                   # Pipeline entrypoint
|
|-- artifact/
|   |-- Brain_tumorbest_model.keras   # Trained model weights (~80 MB)
|
|-- Dockerfile                    # Multi-stage build (Node + Python)
|-- requirements.txt              # Python dependencies
|-- .env                          # Local environment variables
|-- .dockerignore
|-- .gitignore

---

Getting Started

Prerequisites

Requirement	Minimum Version
Python	3.11+
Node.js	22+
Docker (optional)	24+
Trained model file	artifact/Brain_tumorbest_model.keras

---

Option 1 — Docker (Recommended)

The Docker image bundles the backend, frontend, and model into a single container.

Build and run locally:

docker build -t brain-tumor-classifier .
docker run -p 8000:8000 brain-tumor-classifier

Pull from Docker Hub:

docker pull dbosmrt/brain_tumor:1.0
docker run -p 8000:8000 dbosmrt/brain_tumor:1.0

Open http://localhost:8000 in your browser. The React frontend will load automatically.

---

Option 2 — Local Development

This runs the backend and frontend as separate processes with hot-reload.

1. Clone the repository

git clone https://github.com/dbosmrt/Brain-Tumor-Classification.git
cd Brain-Tumor-Classification

2. Set up the Python backend

python -m venv btvenv
btvenv\Scripts\activate        # Windows
# source btvenv/bin/activate   # macOS / Linux

pip install -r requirements.txt

3. Configure the environment

Create a .env file in the project root (or edit the existing one):

MODEL_PATH=C:\path\to\artifact\Brain_tumorbest_model.keras

Adjust the path to match your local file system.

4. Start the API server

uvicorn app.server.api.api:app --reload --port 8000

The API will be available at http://localhost:8000/api/health.

5. Start the frontend dev server

Open a second terminal:

cd app/client
npm install
npm run dev

Vite will start on http://localhost:5173 and proxy API requests to the backend automatically.

---

API Reference

All API routes are prefixed with /api.

Method	Endpoint	Description
GET	/api/health	Returns server status and whether the model is loaded.
POST	/api/predict	Accepts a multipart image upload and returns classification probabilities.

POST /api/predict

Request:

Content-Type: multipart/form-data
Field: file (image/png, image/jpeg, etc.)
Max size: 10 MB

Response:

{
  "glioma": 0.85,
  "meningioma": 0.05,
  "pituitary": 0.02,
  "no_tumor": 0.08,
  "predicted_class": "glioma"
}

Each value represents the softmax probability for that class. predicted_class is the label with the highest probability.

---

Model Training Pipeline

The model/ directory contains a modular training pipeline. It is excluded from the Docker image since only the trained artifact is needed for inference.

Pipeline stages:

Module	Responsibility
config.py	Centralizes hyperparameters (image size, batch size, learning rate, epochs).
data.py	Loads training, validation, and test splits using image_dataset_from_directory.
preprocess.py	Applies training-time preprocessing (resize to 224x224, RGB conversion).
model.py	Builds EfficientNetB1 with GlobalAveragePooling, Dropout (0.3), and a 4-class softmax head.
train.py	Runs the training loop with early stopping (patience=5) and checkpoint saving.
evaluate.py	Generates accuracy, AUC, precision, recall metrics and confusion matrices.
main.py	Orchestrates the full pipeline end-to-end.

Run the training pipeline:

python -m model.main

Training expects a directory structure with class-labeled subfolders:

Training/
|-- glioma/
|-- meningioma/
|-- no_tumor/
|-- pituitary/

Update the dataset paths in model/config.py before running.

---

Architecture Overview

                          +----------------------------+
                          |        Docker Container     |
                          |                            |
  Browser Request   ----> |   Uvicorn (port 8000)      |
  (http://host:8000)      |        |                   |
                          |        v                   |
                          |   FastAPI (api.py)          |
                          |     |           |          |
                          |     |     /api/predict     |
                          |     |     /api/health      |
                          |     |                      |
                          |   Catch-all route           |
                          |     serves React SPA        |
                          |     from /server/static/    |
                          |                            |
                          |   Predictor (predict.py)    |
                          |     OpenCV preprocessing    |
                          |     EfficientNetB1 model    |
                          |     (Brain_tumorbest.keras) |
                          +----------------------------+

In production (Docker), the FastAPI server handles both API requests and static file serving. During development, Vite runs separately and proxies API calls to the backend.

---

Environment Variables

Variable	Description	Default
MODEL_PATH	Absolute path to the .keras model file.	Set in .env (local) or Dockerfile (Docker)

---

Dependencies

Python (defined in requirements.txt):

Package	Version	Purpose
tensorflow	2.21.0	Deep learning framework
numpy	2.4.4	Numerical operations
opencv-python	4.13.0.92	Image reading and preprocessing
fastapi	0.136.1	REST API framework
uvicorn	0.46.0	ASGI server
pydantic	2.13.3	Request/response validation
python-dotenv	1.2.2	Environment variable loading
python-multipart	0.0.27	File upload parsing
scikit-learn	>=1.6.0	Training evaluation metrics
matplotlib	>=3.10.0	Training visualization
seaborn	>=0.13.0	Confusion matrix plotting

JavaScript (defined in app/client/package.json):

Package	Purpose
react / react-dom	UI framework
vite	Build tool and dev server
tailwindcss	Utility-first CSS framework
recharts	Chart components for confidence visualization
lucide-react	Icon library

---

_{Built by Deepanshu Bhatt}