charlykso/melanoma-classifier

🎯 Intelligent Diagnostic Agent for Early Detection of Human Melanoma

An AI-powered web application for melanoma detection using a hybrid CNN-Transformer model with explainable AI (Grad-CAM) heatmaps.

Version: 1.0 | Status: Production Ready | License: MIT

---

📋 Table of Contents

• Features
• Demo
• Quick Start (5 Minutes)
• System Requirements
• Detailed Setup
• Usage
• Project Structure
• API Documentation
• Troubleshooting
• Contributing

---

✨ Features

✅ Real-time Melanoma Prediction — Binary classification (Benign/Malignant)
✅ Explainable AI — Grad-CAM heatmaps highlight suspicious regions
✅ Image Verification — Rejects non-dermoscopic images
✅ User Authentication — JWT-based role-based access control
✅ Dermatologist Dashboard — Review predictions & provide feedback
✅ Feedback Analytics — Track model agreement rates
✅ Corrective Fine-tuning — Auto-retrain model from expert feedback
✅ Admin Panel — Manage users & platform settings
✅ Cloud Storage — Cloudinary integration for image hosting
✅ RESTful API — FastAPI with interactive Swagger docs

---

🎬 Demo

Frontend UI:

• 📸 Drag & drop image upload
• 🎨 Visual heatmap overlay
• 📊 Confidence scores & metrics

Live API: http://localhost:8000/docs (after setup)

---

⚡ Quick Start (5 Minutes)

Prerequisites

✓ Python 3.10+
✓ Node.js 18+
✓ Git

1️⃣ Clone Repository

git clone https://github.com/yourusername/melanoma-diagnostic-agent.git
cd melanoma-diagnostic-agent

2️⃣ Setup Backend (Terminal 1)

# Activate virtual environment
python -m venv project-env
project-env\Scripts\activate       # Windows
source project-env/bin/activate    # Linux/Mac

# Install dependencies
cd project-api
pip install -r requirements.txt

# Ensure model exists
# Copy melanoma_model.pth to project-api/models/

# Start backend
uvicorn main:app --reload --port 8000

✅ Visit: http://localhost:8000/docs

3️⃣ Setup Frontend (Terminal 2)

cd project-spa
npm install
npm run dev

✅ Visit: http://localhost:5173

4️⃣ Test It

1. Open http://localhost:5173 in browser
2. Register as Patient
3. Upload a dermoscopic image
4. Boom! 💥 See prediction + heatmap

---

🖥️ System Requirements

Minimum Hardware

Component	Requirement
CPU	4 cores (i5 or equivalent)
RAM	8 GB (16 GB recommended)
GPU	Optional (NVIDIA CUDA for speed)
Storage	20 GB free
Browser	Chrome, Firefox, Edge, Safari

Software

Tool	Version
Python	3.10+
Node.js	18+
Docker	Latest (optional)

---

📦 Detailed Setup

Backend Setup

Step 1: Create Python Environment

# Windows
python -m venv project-env
project-env\Scripts\activate

# Linux/Mac
python3 -m venv project-env
source project-env/bin/activate

Verify activation: You should see (project-env) prefix in terminal.

Step 2: Install Python Dependencies

cd project-api
pip install -r requirements.txt

Expected packages:

• fastapi — Web framework
• torch — Deep learning (PyTorch)
• torchvision — Image processing
• sqlalchemy — Database ORM
• pydantic — Data validation
• cloudinary — Cloud storage

Step 3: Download Pre-trained Model

# Download from HuggingFace
# https://huggingface.co/charlykso/melanoma-classifier
# Or copy trained model:
cp ../path/to/melanoma_model.pth ./models/

File location (critical): project-api/models/melanoma_model.pth

Step 4: Configure Environment Variables

# Create .env file in project-api/
CLOUDINARY_API_KEY=your_key
CLOUDINARY_API_SECRET=your_secret
DATABASE_URL=postgresql://user:password@localhost/melanoma
JWT_SECRET=your-secret-key

Step 5: Initialize Database (if using PostgreSQL)

alembic upgrade head

Step 6: Start Backend Server

uvicorn main:app --reload --port 8000

Success Indicators:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete

Check API health:

curl http://localhost:8000/health
# Response: {"status": "healthy"}

---

Frontend Setup

Step 1: Install Node Dependencies

cd project-spa
npm install
# or
yarn install

Packages installed:

• react — UI framework
• typescript — Type safety
• axios — HTTP client
• tailwindcss — Styling
• vite — Build tool

Step 2: Configure API Endpoint (Optional)

# Create .env in project-spa/
VITE_API_URL=http://localhost:8000

Default: http://localhost:8000

Step 3: Start Development Server

npm run dev
# or
yarn dev

Success Indicators:

  Local:        http://localhost:5173/
  press h to show help

Step 4: Open in Browser

http://localhost:5173

---

🎮 Usage

1. Register Account

• Click "Register"
• Enter email & password
• Select role: Patient (or Dermatologist if available)
• Click "Sign Up"

2. Upload Image

• On dashboard, click "Upload Image"
• Drag & drop a dermoscopic skin lesion image (JPG/PNG)
• Or click to browse files

3. Get Prediction

• System verifies it's dermoscopic
• Runs melanoma classifier
• Generates Grad-CAM heatmap
• Wait 3-5 seconds ⏳

4. View Results

• Prediction: Benign / Malignant
• Confidence: 0-100%
• Heatmap: Red regions = model focus areas
• History: All predictions saved

5. Dermatologist Review (if available)

• Log in as Dermatologist
• Review assigned cases
• Submit feedback (ground truth diagnosis)
• Track agreement rates

---

📁 Project Structure

melanoma-diagnostic-agent/
│
├── project-api/                 # Backend (FastAPI + PyTorch)
│   ├── main.py                 # Entry point
│   ├── requirements.txt         # Python dependencies
│   ├── app/
│   │   ├── config.py           # Settings
│   │   ├── routers/            # API endpoints
│   │   ├── models/             # ML models code
│   │   ├── services/           # Business logic
│   │   ├── database/           # Database setup
│   │   └── schemas/            # Request/response schemas
│   ├── models/                 # Model weights
│   │   └── melanoma_model.pth  # Pre-trained model (REQUIRED)
│   └── static/                 # Generated heatmaps
│
├── project-spa/                 # Frontend (React + TypeScript)
│   ├── package.json            # npm dependencies
│   ├── src/
│   │   ├── main.tsx            # Entry point
│   │   ├── App.tsx             # Main component
│   │   ├── pages/              # Page components
│   │   ├── components/         # Reusable components
│   │   ├── services/           # API client
│   │   └── styles/             # CSS/Tailwind
│   └── vite.config.ts          # Vite configuration
│
├── project-env/                 # Python virtual environment
│   ├── Scripts/                # Executables (Windows)
│   └── lib/site-packages/      # Installed packages
│
├── Software_Documentation.md    # Full documentation
└── README.md                    # This file

---

🔌 API Documentation

Interactive Docs

Visit: http://localhost:8000/docs (Swagger UI)

Key Endpoints

Authentication

POST /auth/register       # Create account
POST /auth/login          # Login
GET  /auth/me            # Get profile

Predictions

POST /predict            # Upload image → get prediction
GET  /predictions        # Prediction history
GET  /predictions/{id}   # Single prediction

Dermatologist

GET  /dermatologist/stats       # Dashboard stats
GET  /dermatologist/predictions # Assigned cases
POST /predictions/{id}/feedback # Submit diagnosis

Admin

GET  /admin/stats        # Platform statistics
GET  /admin/users        # User management

---

🐛 Troubleshooting

Backend Issues

Problem	Solution
ModuleNotFoundError: No module named 'torch'	Run pip install -r requirements.txt again, ensure virtual env activated
Port 8000 already in use	Use different port: uvicorn main:app --port 8001
Model not found error	Download melanoma_model.pth and place in models/ directory
Database connection error	Ensure PostgreSQL running: psql -U postgres
CORS error in browser	Check backend is running on correct port (8000)

Frontend Issues

Problem	Solution
npm ERR! Cannot find module	Delete node_modules/ and package-lock.json, then npm install
Port 3000/5173 already in use	Kill process: lsof -ti:5173 | xargs kill -9 (Linux/Mac) or use different port
Blank/white page	Check browser console (F12), ensure backend URL in .env correct
Image upload not working	Verify backend running & model loaded at http://localhost:8000/docs

General Issues

Problem	Solution
Connection refused	Ensure both backend & frontend are running in separate terminals
Slow inference (>10s)	Model running on CPU. Install GPU drivers for CUDA acceleration
Database errors	If using SQLite (default), ensure data/ folder exists with permissions

---

✅ Verification Checklist

After setup, verify everything works:

Backend Check

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

# Should return:
# {"status": "healthy", "model_loaded": true}

Frontend Check

• ✅ Page loads without white/blank screen
• ✅ No errors in browser console (F12 → Console tab)
• ✅ Can see login/register forms
• ✅ Images upload without errors

Full System Test

1. Register account
2. Upload test dermoscopic image
3. See prediction result
4. View Grad-CAM heatmap
5. Result appears in prediction history

---

🚀 Next Steps

After successful setup:

Development

# Run with auto-reload
uvicorn main:app --reload

# Run tests
pytest project-api/tests/

# Format code
black project-api/

Production Deployment

# Using Docker
docker-compose up --build

# Or manual:
# - Set DEBUG=False in .env
# - Configure ALLOWED_HOSTS
# - Setup proper database (PostgreSQL recommended)
# - Use production server (Gunicorn)

Model Training

cd project-api
python train.py --epochs 50 --batch-size 32

---

📚 Documentation

• Full Setup Guide: See Software_Documentation.md
• API Reference: http://localhost:8000/docs (after startup)
• Model Details: See project-api/README.md
• Frontend Guide: See project-spa/README.md

---

🤝 Contributing

Contributions welcome! Please:

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

---

📄 License

This project is licensed under the MIT License. See LICENSE file for details.

---

👨‍💼 Author

Charles — MSc Thesis Project
Intelligent Diagnostic Agent for Early Detection of Human Melanoma

---

🆘 Support

Issues? Check:

1. Troubleshooting section above
2. API docs: http://localhost:8000/docs
3. Full docs: Software_Documentation.md

Contact: [your-email@example.com]

---

🎓 Citation

If you use this project in research, please cite:

@thesis{melanoma2026,
  author = {Charles},
  title = {Intelligent Diagnostic Agent for Early Detection of Human Melanoma},
  school = {University Name},
  year = {2026}
}

---

📊 Project Status

Component	Status
Backend API	✅ Production Ready
Frontend UI	✅ Production Ready
Model Training	✅ Completed (ISIC 2018)
Deployment	✅ Docker Support
Tests	🔄 In Progress
Documentation	✅ Complete

---

Last Updated: April 2026 | Version: 1.0