You can deploy this model and start earning money today!

charlykso/
melanoma-classifier

Name: melanoma-classifier
Availability: InStock

Views

No views yet

🎯 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

✨ 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

bash

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

1️⃣ Clone Repository

bash

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

2️⃣ Setup Backend (Terminal 1)

bash

# 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)

bash

cd project-spa
npm install
npm run dev

✅ Visit: http://localhost:5173

4️⃣ Test It

Open http://localhost:5173 in browser
Register as Patient
Upload a dermoscopic image
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

bash

# 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

bash

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

bash

# 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

bash

# 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:

bash

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

Frontend Setup

Step 1: Install Node Dependencies

bash

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)

bash

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

Default: http://localhost:8000

Step 3: Start Development Server

bash

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

bash

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

Predictions

bash

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

Dermatologist

bash

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

Admin

bash

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

bash

# 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

Register account
Upload test dermoscopic image
See prediction result
View Grad-CAM heatmap
Result appears in prediction history

🚀 Next Steps

After successful setup:

Development

bash

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

# Run tests
pytest project-api/tests/

# Format code
black project-api/

Production Deployment

bash

# 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

bash

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:

Fork repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
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:

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

Contact: [your-email@example.com]

🎓 Citation

If you use this project in research, please cite:

bibtex

@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