# mhw32/derm-ai architecture

> Architecture diagram of the GitHub repository mhw32/derm-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mhw32/derm-ai
- Repository: https://github.com/mhw32/derm-ai

## Overview

##### Project type and purpose
- Project type: A backend API service wrapping a deep-learning model (PyTorch) for skin-disease classification. It includes an offline data-scraping + training pipeline and an online inference service (Flask) deployed (via Procfile/runtime.txt) to Heroku.
- Purpose:
– Offline: scrape raw images, precompute embeddings, train a fine-tuned ResNet152 + custom FC layers, produce a “best” model file.
– Online: expose a single POST `/predict` endpoint that accepts a base64 image and returns a predicted class + score.

##### File structure
Top-level:
- run.py             → entrypoint for the Flask app
- scraper.py         → scripts to download/prepare raw images
- train.py           → training script for the model
- setup.sh           → installs dependencies; downloads raw images & embeddings; pulls pretrained model
- model.py           → defines the PyTorch network architecture (ResNet152 + 2 FC layers)
- config.py          → centralizes paths, hyperparameters, environment flags
- requirements.txt   → Python dependencies (Flask, torch, torchvision, etc.)
- Procfile + runtime.txt → deployment config for Heroku
- trained_models/    → serialized model checkpoint (`model_best.pth.tar`)
Subfolders:
- app/               → Flask application package
– views.py       → HTTP routes (POST `/predict`)
– helper.py      → image decoding, preprocessing logic
- utils/             → shared utilities
– data.py        → dataset loaders, transforms
– embeddings.py  → code to generate ResNet152 embeddings
No traditional database; models and data live on the file system.

##### Pull additional insights from README
- Uses pretrained ResNet152 from ImageNet; fine-tune by adding 2 FC layers
- Accuracy ~53% on held-out test data
- Single endpoint: `/predict` expects `{ "image": "<base64>" }`, returns `{ "class": X, "score": Y }`

a. Main components
1. Client (Consumer of the API)
2. Web/API Layer
– Flask app (run.py → app/views.py → uses helper.py)
3. Inference Engine
– model.py loads `model_best.pth.tar` using PyTorch
– utils/data.py & helper.py handle transforms (resize, normalize)
4. Offline Pipeline
– Scraper (scraper.py) to pull images from DermNet
– Embedding generator (utils/embeddings.py) to precompute ResNet features
– Training module (train.py) which uses data.py and model.py to train & save checkpoint
5. File Storage
– Raw images (train/, test/)
– Embeddings (train_emb/, test_emb/)
– Trained model (`trained_models/`)
6. Deployment
– Heroku (Procfile, runtime.txt)
– setup.sh for one-click bootstrap
b. Relationships & interactions
– Client → (HTTP POST) → Flask API `/predict`
– API layer → loads model checkpoint → performs inference → returns JSON
– Offline pipeline components chained: Scraper → Raw image store → Embedding generator → Embedding store → Trainer → Model store
– Deployment config picks up run.py, requirements.txt, runtime.txt
c. Architectural patterns / design principles
– Separation of concerns:
- API layer vs. ML logic vs. data utilities
– Reuse of pretrained model (transfer learning)
– Monolithic service (single process), but logically layered
– Offline vs. online components clearly separated
d. Key technologies / frameworks
– Flask (web framework)
– PyTorch + torchvision (deep learning)
– Heroku (PaaS for deployment)
– Python scripting (scraper, training, setup)

##### Key reminders
- Python modules that perform distinct roles (app/, utils/, model.py, scraper.py, train.py).
- Both offline and online workflows and how they share the model artifact.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Offline Pipeline"
        direction TB
        DermNet[/"DermNet Website"/]:::external
        Scraper["scraper.py"]:::service
        DermNet --> Scraper
        RawImgs["Raw Images (train/, test/)"]:::storage
        Scraper --> RawImgs
        EmbGen["utils/embeddings.py"]:::service
        RawImgs --> EmbGen
        EmbStore["Embeddings (train_emb/, test_emb/)"]:::storage
        EmbGen --> EmbStore
        DataUtils["utils/data.py"]:::service
        EmbStore --> DataUtils
        Trainer["train.py"]:::service
        DataUtils --> Trainer
        ModelStore["model_best.pth.tar"]:::storage
        Trainer --> ModelStore
    end

    subgraph "Online Service"
        direction TB
        Client(["Client"]):::external
        APIEntrypoint["run.py"]:::service
        Views["app/views.py"]:::service
        Helper["app/helper.py"]:::service
        InferenceData["utils/data.py"]:::service
        InferenceEngine["model.py"]:::service
        Checkpoint["model_best.pth.tar"]:::storage
        Client --> APIEntrypoint
        APIEntrypoint --> Views
        Views --> Helper
        Helper --> InferenceData
        InferenceData --> InferenceEngine
        Checkpoint --> InferenceEngine
        InferenceEngine -->|"predicted class, score"| Views
        Views -->|"JSON response"| Client
    end

    subgraph "Deployment & Config"
        direction TB
        Config["config.py"]:::config
        Req["requirements.txt"]:::config
        Proc["Procfile"]:::config
        Runtime["runtime.txt"]:::config
        Setup["setup.sh"]:::config
    end

    Setup --> Scraper
    Setup --> APIEntrypoint
    Config -.-> Scraper
    Config -.-> Trainer
    Config -.-> APIEntrypoint
    Req -.-> Scraper
    Req -.-> APIEntrypoint
    Proc -.-> APIEntrypoint
    Runtime -.-> APIEntrypoint

    click APIEntrypoint "https://github.com/mhw32/derm-ai/blob/master/run.py"
    click Views "https://github.com/mhw32/derm-ai/blob/master/app/views.py"
    click Helper "https://github.com/mhw32/derm-ai/blob/master/app/helper.py"
    click InferenceEngine "https://github.com/mhw32/derm-ai/blob/master/model.py"
    click InferenceData "https://github.com/mhw32/derm-ai/blob/master/utils/data.py"
    click Checkpoint "https://github.com/mhw32/derm-ai/blob/master/trained_models/model_best.pth.tar"
    click Scraper "https://github.com/mhw32/derm-ai/blob/master/scraper.py"
    click EmbGen "https://github.com/mhw32/derm-ai/blob/master/utils/embeddings.py"
    click Trainer "https://github.com/mhw32/derm-ai/blob/master/train.py"
    click DataUtils "https://github.com/mhw32/derm-ai/blob/master/utils/data.py"
    click Config "https://github.com/mhw32/derm-ai/blob/master/config.py"
    click Proc "https://github.com/mhw32/derm-ai/tree/master/Procfile"
    click Runtime "https://github.com/mhw32/derm-ai/blob/master/runtime.txt"
    click Setup "https://github.com/mhw32/derm-ai/blob/master/setup.sh"
    click Req "https://github.com/mhw32/derm-ai/blob/master/requirements.txt"

    classDef service fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef storage fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#F57C00,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#D1C4E9,stroke:#6A1B9A,stroke-width:1px
```
