README.md

---
title: DermAI Skin Disease Classifier
emoji: 🔬
colorFrom: blue
colorTo: blue
sdk: docker
pinned: false
license: mit
app_port: 7860
---

<div align="center">

# 🔬 DermAI — Skin Disease Classifier

### AI-Powered Dermatology Assistant

[![Live Demo](https://img.shields.io/badge/🤗%20Live%20Demo-HuggingFace%20Spaces-blue?style=for-the-badge)](https://huggingface.co/spaces/Yashvardhan1/dermaAI)
[![GitHub](https://img.shields.io/badge/GitHub-yashvardhanshah-black?style=for-the-badge&logo=github)](https://github.com/yashvardhanshah/dermAI)
[![Python](https://img.shields.io/badge/Python-3.12-blue?style=for-the-badge&logo=python)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.111-green?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com)
[![Streamlit](https://img.shields.io/badge/Streamlit-1.35-red?style=for-the-badge&logo=streamlit)](https://streamlit.io)
[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)

*Upload a skin photo. Get an AI diagnosis in seconds.*

![DermAI Banner](https://img.shields.io/badge/ResNet--34-448×448px-purple?style=flat-square) ![Classes](https://img.shields.io/badge/21%20Skin%20Conditions-Classified-success?style=flat-square) ![Deployment](https://img.shields.io/badge/Deployed-HuggingFace%20Spaces-orange?style=flat-square)

</div>

---

## 📋 Table of Contents

- [Overview](#-overview)
- [Features](#-features)
- [Tech Stack](#-tech-stack)
- [Model Architecture](#-model-architecture)
- [Disease Classes](#-disease-classes)
- [Project Structure](#-project-structure)
- [Local Setup](#-local-setup)
- [API Reference](#-api-reference)
- [Deployment](#-deployment)
- [Screenshots](#-screenshots)
- [Disclaimer](#-medical-disclaimer)
- [License](#-license)
- [Author](#-author)

---

## 🧠 Overview

**DermAI** is a full-stack AI-powered web application that classifies skin diseases from photographs using deep learning. Built with a fine-tuned ResNet-34 convolutional neural network trained via the fastai framework, it identifies 21 distinct skin conditions and provides detailed medical information, treatment options, and urgency flags for conditions requiring immediate attention.

The application features a **FastAPI** REST backend for model inference and a **Streamlit** multi-page frontend — both running concurrently inside a single Docker container deployed on **Hugging Face Spaces**.

---

## ✨ Features

| Feature | Description |
|---|---|
| 🔬 **AI Diagnosis** | Upload any skin photo and receive top-3 predictions with confidence scores |
| 📖 **Disease Encyclopedia** | Detailed profiles for all 21 classifiable conditions |
| 🏥 **Dermatology Hub** | Expert articles on skincare, sun protection, and dermatology tips |
| ⚠️ **Urgency Flags** | Automatic red alerts for high-risk conditions (Skin Cancer, Actinic Keratosis) |
| 🌙 **Dark UI** | Modern dark-themed interface with responsive layout |
| ⚡ **Fast Inference** | Direct tensor inference bypassing DataLoader threading issues |
| 🐳 **Dockerized** | Single-container deployment with supervisor managing both services |

---

## 🛠 Tech Stack

### Backend
- **FastAPI** — REST API framework
- **Uvicorn** — ASGI server
- **fastai / PyTorch** — Model loading and inference
- **Pydantic** — Data validation and serialization

### Frontend
- **Streamlit** — Multi-page web interface
- **Custom CSS** — Dark theme with Orbitron + DM Sans typography

### ML / Model
- **Architecture:** ResNet-34 (pretrained on ImageNet, fine-tuned)
- **Framework:** fastai 2.7
- **Input Size:** 448×448px (progressive resizing from 224→448)
- **Output:** Top-3 predictions with softmax confidence scores

### Infrastructure
- **Docker** — Containerization
- **Supervisor** — Process management (FastAPI + Streamlit)
- **Hugging Face Spaces** — Cloud deployment
- **Git LFS** — Large file storage for model weights

---

## 🤖 Model Architecture

```
Input Image (any size)
        ↓
    Resize to 448×448
        ↓
    Normalization (ImageNet stats)
        ↓
    ResNet-34 Backbone
    (pretrained on ImageNet)
        ↓
    Custom Classification Head
        ↓
    Softmax (21 classes)
        ↓
    Top-3 Predictions + Confidence Scores
```

### Training Details
- **Base Model:** ResNet-34 (ImageNet pretrained)
- **Training Strategy:** Progressive resizing (224 → 448)
- **Framework:** fastai with 1-cycle learning rate policy
- **Augmentations:** Random flip, rotation, zoom, lighting adjustments
- **Optimizer:** Adam with weight decay

---

## 🦠 Disease Classes

The model classifies the following 21 skin conditions:

| # | Medical Name | Category |
|---|---|---|
| 1 | Acne | Inflammatory |
| 2 | Rosacea | Inflammatory |
| 3 | Tinea (Ringworm) | Fungal |
| 4 | Candidiasis | Fungal |
| 5 | Warts | Viral |
| 6 | Eczema / Dermatitis | Inflammatory |
| 7 | Psoriasis | Autoimmune |
| 8 | Normal Skin | Healthy |
| 9 | Skin Cancer | Oncological ⚠️ |
| 10 | Actinic Keratosis | Pre-Cancerous ⚠️ |
| 11 | Benign Tumors | Growth |
| 12 | Bullous Disorders | Autoimmune |
| 13 | Drug Eruptions | Allergic |
| 14 | Infestations & Bites | Parasitic |
| 15 | Lichen Disorders | Inflammatory |
| 16 | Lupus-Related Conditions | Autoimmune |
| 17 | Moles (Nevi) | Growth |
| 18 | Seborrheic Keratoses | Growth |
| 19 | Vascular Tumors | Growth |
| 20 | Vasculitis | Inflammatory |
| 21 | Vitiligo | Autoimmune |

---

## 📁 Project Structure

```
dermAI/
├── app/
│   ├── backend/
│   │   ├── main.py              # FastAPI app & endpoints
│   │   ├── model.py             # Model loading & inference
│   │   ├── schemas.py           # Pydantic models
│   │   └── __init__.py
│   ├── frontend/
│   │   ├── Home.py              # Streamlit entry point
│   │   ├── styles.py            # Global CSS injection
│   │   ├── .streamlit/
│   │   │   └── config.toml      # Streamlit configuration
│   │   └── pages/
│   │       ├── 1_Diagnosis.py       # Image upload & prediction
│   │       ├── 2_Encyclopedia.py    # Disease database browser
│   │       ├── 3_Dermatology_Hub.py # Articles & tips
│   │       └── 4_About_FAQ.py       # About & FAQ
│   └── data/
│       └── disease_info.py      # Disease info database (21 conditions)
├── skin_disease_classifier.pkl  # Trained model weights (88MB, Git LFS)
├── Dockerfile                   # Multi-service Docker container
├── requirements.txt             # Python dependencies
└── README.md
```

---

## 🚀 Local Setup

### Prerequisites
- Python 3.12+
- Git LFS
- Conda (recommended) or virtualenv

### 1. Clone the repository
```bash
git clone https://github.com/yashvardhanshah/dermAI.git
cd dermAI
```

### 2. Create environment & install dependencies
```bash
conda create -n dermai python=3.12
conda activate dermai
pip install -r requirements.txt
```

### 3. Set environment variable (Windows)
```bash
set KMP_DUPLICATE_LIB_OK=TRUE
```

### 4. Start the FastAPI backend
```bash
cd app
uvicorn backend.main:app --reload --port 8000
```

### 5. Start the Streamlit frontend (new terminal)
```bash
cd app/frontend
streamlit run Home.py
```

### 6. Open in browser
- **App:** http://localhost:8501
- **API Docs:** http://localhost:8000/docs

---

## 📡 API Reference

### Base URL
```
https://huggingface.co/spaces/Yashvardhan1/dermaAI (production)
http://localhost:8000 (local)
```

### Endpoints

#### `GET /health`
Health check — returns model load status.

```json
{
  "status": "ok",
  "model_loaded": true,
  "version": "1.0.0"
}
```

#### `POST /predict`
Upload a skin image and receive top-3 predictions.

**Request:** `multipart/form-data` with `file` field (JPEG/PNG/WEBP, max 15MB)

**Response:**
```json
{
  "top3": [
    {
      "label": "Acne",
      "friendly_name": "Acne / Pimples",
      "confidence": 0.8923
    },
    ...
  ],
  "disclaimer": "This tool is for educational purposes only..."
}
```

#### `GET /diseases`
Returns summary list of all 21 classifiable conditions.

#### `GET /disease/{disease_key}`
Returns full detail for a single condition including symptoms, causes, treatments, and when to see a doctor.

---

## 🐳 Deployment

The app is deployed on **Hugging Face Spaces** as a Docker Space.

### Architecture
```
Docker Container
├── Supervisor (process manager)
│   ├── FastAPI (port 8000) — model inference API
│   └── Streamlit (port 7860) — web UI (exposed)
└── skin_disease_classifier.pkl — model weights
```

### Deploy your own
1. Fork this repository
2. Create a new HuggingFace Space (Docker SDK)
3. Push code to the Space repository
4. The app builds and deploys automatically

---

## ⚠️ Medical Disclaimer

> **DermAI is an educational tool only and does NOT constitute medical advice.**
> 
> This application is designed for informational and educational purposes. It should NOT be used as a substitute for professional medical diagnosis, advice, or treatment. Always consult a qualified dermatologist or healthcare professional for any skin concerns.
>
> Results flagged as **Skin Cancer** or **Actinic Keratosis** should be evaluated by a medical professional **immediately**.

---

## 📄 License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

```
MIT License

Copyright (c) 2026 Yashvardhan Shah

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
```

---

## 👤 Author

**Yashvardhan Shah**

[![GitHub](https://img.shields.io/badge/GitHub-yashvardhanshah-black?style=flat-square&logo=github)](https://github.com/yashvardhanshah)
[![HuggingFace](https://img.shields.io/badge/HuggingFace-Yashvardhan1-orange?style=flat-square)](https://huggingface.co/Yashvardhan1)

---

<div align="center">

**⭐ Star this repo if you found it useful!**

*Built with ❤️ using FastAPI, Streamlit, and fastai*

</div>