Brain Tumour Detection

Deep-learning MRI classification with explainable AI, production inference pipeline, and full-stack web interface.

---

Overview

Brain Tumour Detection is a production-ready, full-stack application that classifies MRI brain scans into four categories using deep learning:

The system supports five model architectures (including MambaVision, the official state-of-the-art vision Mamba model), provides Grad-CAM visual explanations, offers async training with experiment tracking, and ships with a React dashboard for real-time monitoring.

---

Architecture

Browser (React 18 + Vite + Tailwind CSS)
         │  port 3000
         ▼
  Node.js / Express API          ← port 5000
  ├── /api/upload                 Multer file upload + SQLite storage
  ├── /api/preprocess             OpenCV preprocessing pipeline
  ├── /api/segment                Image segmentation
  ├── /api/features               Feature extraction
  ├── /api/classify               EDN-SVM classifier
  ├── /api/batch                  Batch processing
  ├── /api/results                Result retrieval
  ├── /api/metrics                Aggregated metrics
  └── /api/compare                Model comparison
         │  proxies AI requests
         ▼
  Python / FastAPI / PyTorch     ← port 8000
  ├── /api/v1/health              Liveness probe
  ├── /api/v1/predict             Single-image inference + Grad-CAM
  ├── /api/v1/train               Model training (sync + async)
  ├── /api/v1/evaluate            Model evaluation on test set
  ├── /api/v1/dataset/*           Dataset management
  ├── /api/v1/preprocess/*        Image preprocessing & quality check
  ├── /api/v1/auth/*              JWT authentication + RBAC
  ├── /api/v1/performance/*       Performance monitoring + benchmarking
  └── /api/v1/dashboard/*         Metrics & monitoring dashboard

---

Technology Stack

---

Prerequisites

---

Quick Start — Docker (Recommended)

The fastest way to run everything:

# 1. Clone the repository
git clone https://github.com/your-org/brain-tumor-detection.git
cd brain-tumor-detection

# 2. Copy environment templates
cp ai-service/.env.example  ai-service/.env
cp backend/.env.example     backend/.env
cp frontend/.env.example    frontend/.env.local

# 3. Set a strong JWT secret
echo "JWT_SECRET_KEY=$(openssl rand -hex 32)" >> ai-service/.env

# 4. Build and start all services
docker compose -f docker/docker-compose.yml up --build -d

# 5. Follow startup logs
docker compose -f docker/docker-compose.yml logs -f

Once healthy:

• Frontend → http://localhost:3000
• Backend API → http://localhost:5000
• AI Service + Swagger → http://localhost:8000/docs

---

Quick Start — Local Development

1. Bootstrap all environments

make setup

On Windows without Make:

# AI service
cd ai-service
.\setup_env.ps1

# Backend
cd ..\backend
npm ci
copy .env.example .env

# Frontend
cd ..\frontend
npm ci
copy .env.example .env.local

2. Configure environment files

ai-service/.env    ← AI service config
backend/.env       ← Backend config
frontend/.env.local ← Frontend config

See the Environment Variables Reference below for all options.

3. Run database migrations

make migrate
# or
cd backend && node database/migrate.js

4. Start all three services

# Terminal 1 — AI Service (port 8000)
cd ai-service
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Terminal 2 — Backend (port 5000)
cd backend
npm run dev

# Terminal 3 — Frontend (port 3000)
cd frontend
npm run dev

---

Usage

Train a model

curl -X POST http://localhost:8000/api/v1/train \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "mambavision",
    "epochs": 30,
    "batch_size": 32,
    "learning_rate": 0.0001,
    "fine_tune": true
  }'

Run inference

curl -X POST http://localhost:8000/api/v1/predict \
  -F "file=@mri_scan.jpg"

Async training (experiment-tracked)

# Start async job
curl -X POST http://localhost:8000/api/v1/train/start \
  -H "Content-Type: application/json" \
  -d '{"model_name": "resnet50", "epochs": 50}'

# Poll status
curl http://localhost:8000/api/v1/train/status/{job_id}

# List all experiments
curl http://localhost:8000/api/v1/train/experiments

---

Model Architectures

All transfer-learning architectures support two-phase fine-tuning: head training first, then selective backbone unfreezing.

---

Dataset

The model expects MRI images organised in class subdirectories:

dataset/raw/
├── Training/
│   ├── glioma/
│   ├── meningioma/
│   ├── notumor/
│   └── pituitary/
└── Testing/
    ├── glioma/
    ├── meningioma/
    ├── notumor/
    └── pituitary/

Prepare the dataset via the API:

# Validate structure
curl -X POST http://localhost:8000/api/v1/dataset/validate

# Split into train/val/test
curl -X POST http://localhost:8000/api/v1/dataset/prepare \
  -H "Content-Type: application/json" \
  -d '{"train_ratio": 0.7, "val_ratio": 0.15, "test_ratio": 0.15}'

---

Testing

# Run all test suites
make test

# Python tests only (with coverage)
make test-ai-coverage

# Frontend tests
cd frontend && npm test

# Backend tests
cd backend && npm test

---

Environment Variables

AI Service (ai-service/.env)

Backend (backend/.env)

Frontend (frontend/.env.local)

---

Makefile Targets

make setup               Bootstrap all three environments
make dev                 Start all services (tmux session)
make test                Run all test suites
make build               Build all production artefacts
make docker-up           Build and start all containers (detached)
make docker-down         Stop and remove containers
make docker-logs         Tail logs from all containers
make migrate             Run SQLite database migrations
make clean               Remove build artefacts and logs

Run make help for the full list.

---

Documentation

---

Project Structure

brain-tumor-detection/
├── ai-service/                  Python / FastAPI / PyTorch
│   ├── app/
│   │   ├── api/                 REST route handlers
│   │   ├── core/                Config, logging
│   │   ├── dataset/             Validation, splitting, stats
│   │   ├── inference/           Pipeline, batch, cache, results
│   │   ├── metrics/             System, inference, training, dashboard
│   │   ├── models/              Architectures, train, predict, evaluate
│   │   ├── performance/         Profiler, benchmark, cache, memory
│   │   ├── preprocessing/       Image pipeline, augmentation, quality
│   │   ├── security/            JWT, auth, roles, rate limiting, audit
│   │   ├── training/            Job store, experiment registry
│   │   └── utils/               Grad-CAM
│   ├── dataset/                 raw/ and processed/ MRI images
│   ├── saved_models/            Trained PyTorch checkpoints
│   ├── tests/                   pytest suite (1,100+ tests)
│   ├── Dockerfile
│   └── requirements.txt
│
├── backend/                     Node.js / Express / SQLite
│   ├── api/                     Route handlers (9 modules)
│   ├── database/                Schema SQL, migrations, db.js
│   ├── middleware/              Upload, error handling, validation
│   ├── pipeline/                Preprocessing, segmentation, classifier
│   ├── server.js
│   └── package.json
│
├── frontend/                    React 18 / Vite / TypeScript
│   ├── src/
│   │   ├── components/          Reusable UI components
│   │   ├── pages/               Route-level page components
│   │   ├── hooks/               Custom React hooks
│   │   ├── api/                 Axios API clients
│   │   ├── context/             React context providers
│   │   └── types/               TypeScript type definitions
│   ├── package.json
│   └── vite.config.ts
│
├── docker/                      Docker Compose configurations
│   ├── docker-compose.yml       Base configuration
│   ├── docker-compose.dev.yml   Development overrides
│   ├── docker-compose.prod.yml  Production overrides
│   ├── Dockerfile.backend
│   └── Dockerfile.frontend
│
├── docs/                        Project documentation
├── scripts/                     Deployment and maintenance scripts
├── .github/workflows/           CI/CD pipeline definitions
├── Makefile                     Developer task automation
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md

---

Contributing

See CONTRIBUTING.md for guidelines on reporting issues, submitting pull requests, and the development workflow.

---

Security

To report a security vulnerability, please follow the process described in SECURITY.md. Do not open a public GitHub issue for security concerns.

---

License

This project is licensed under the MIT License — see LICENSE for details.

---

Acknowledgements

• Brain Tumor MRI Dataset (Kaggle) for training data
• PyTorch team for the deep learning framework
• NVIDIA for the official MambaVision implementation
• Hugging Face for the Transformers library and model hub
• FastAPI for the elegant Python web framework