# nico-curti/deepskin architecture

> Architecture diagram of the GitHub repository nico-curti/deepskin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nico-curti/deepskin
- Repository: https://github.com/nico-curti/deepskin

## Overview

##### Project type and purpose
- Deepskin is an open-source Python library and CLI tool for automated wound analysis from smartphone images.
- It implements a two-step pipeline: (1) deep-learning based semantic segmentation of wound and peri-wound regions (U-Net model with active semi-supervised learning support), (2) hand-crafted feature extraction and regression for PWAT score prediction.

##### Key directories and files
- deepskin/ : core Python modules
- __main__.py – CLI entry point
- model.py & checkpoints.py – model definition & checkpoint management
- segmentation.py – U-Net segmentation wrapper
- imgproc.py – morphology ops for peri-wound ROI
- features.py – texture/morphology feature extractors
- pwat.py – regression model for PWAT scoring
- constants.py – fixed parameters
- docs/ : Sphinx docs and notebooks demonstrating usage
- environment.yml / requirements.txt / setup.py / pyproject.toml : build & dependency configs
- .github/workflows/ : CI pipelines for tests and docs

##### Major components
a. User Interface
- CLI (deepskin command) and Python API
b. Pipeline Controller
- __main__.py orchestrates steps based on CLI flags
c. Segmentation Subsystem
- Model loader (checkpoints.py)
- Deep Learning model (model.py)
- Segmentation wrapper (segmentation.py)
d. Image Processing Subsystem
- Morphological operations to derive peri-wound mask (imgproc.py)
e. Feature Extraction Subsystem
- Feature calculators (features.py)
f. PWAT Prediction Subsystem
- Regression model (pwat.py)
g. Persistence & I/O
- Read/write images and masks (OpenCV I/O)
- Save results (console, PNG files)
h. External Dependencies
- TensorFlow / Keras, OpenCV, NumPy, scikit-learn, etc.

##### Data flow and interactions
- CLI calls Pipeline Controller →
- invokes Segmentation Subsystem: loads model → predicts wound mask
- sends mask → Image Processing Subsystem for peri-wound mask
- passes ROIs → Feature Extraction Subsystem → feature vectors
- passes features → PWAT Prediction Subsystem → PWAT score
- outputs mask & score back to User

##### Architectural patterns & design principles
- Modular layering: separation of concerns between segmentation, image processing, feature extraction, and prediction.
- Plugin-style extensibility: new segmentation models or feature sets can be added in dedicated modules.
- Single responsibility: each Python module handles one pipeline step.
- CLI front-controller pattern via __main__.

##### Technologies & frameworks
- Python 3.5+
- TensorFlow/Keras for U-Net model
- OpenCV for image I/O & morphology
- NumPy/Pandas for data handling
- scikit-learn (or similar) for regression
- Sphinx for documentation
- GitHub Actions for CI

##### Final checklist for the engineer
- Technologies, file names, and interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface"
        direction TB
        User["User"]:::external
        CLI["CLI (deepskin/__main__.py)"]:::ui
        API["Python API (deepskin/__init__.py)"]:::ui
    end

    %% Pipeline Controller
    Pipeline["Pipeline Controller (__main__.py)"]:::processing

    %% Segmentation Subsystem
    subgraph "Segmentation Subsystem"
        direction TB
        Checkpoints["Checkpoint Manager (checkpoints.py)"]:::processing
        Model["U-Net Model (model.py)"]:::processing
        Segmentation["Segmentation Wrapper (segmentation.py)"]:::processing
    end

    %% Image Processing Subsystem
    subgraph "Image Processing Subsystem"
        direction TB
        ImgProc["Morphology Ops (imgproc.py)"]:::processing
    end

    %% Feature Extraction Subsystem
    subgraph "Feature Extraction Subsystem"
        direction TB
        Features["Feature Calculators (features.py)"]:::processing
    end

    %% PWAT Prediction Subsystem
    subgraph "PWAT Prediction Subsystem"
        direction TB
        PWAT["Regression Model (pwat.py)"]:::processing
    end

    %% Configuration & Constants
    subgraph "Configuration & Constants"
        direction TB
        Constants["Constants (constants.py)"]:::config
        Setup["setup.py"]:::config
        Pyproject["pyproject.toml"]:::config
        Requirements["requirements.txt"]:::config
        Env["environment.yml"]:::config
    end

    %% Documentation & CI
    subgraph "Documentation & CI"
        direction TB
        Docs["Documentation (docs/)"]:::docsci
        CI1["CI - Python Tests (.github/workflows/python.yml)"]:::docsci
        CI2["CI - Docs Build (.github/workflows/docs.yml)"]:::docsci
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        TF["TensorFlow / Keras"]:::external
        OpenCV["OpenCV"]:::external
        NumPy["NumPy / Pandas"]:::external
        SKLearn["scikit-learn"]:::external
    end

    %% Data Flow
    User --> CLI
    User --> API
    CLI --> Pipeline
    API --> Pipeline

    Pipeline --> Segmentation
    Segmentation --> ImgProc
    ImgProc --> Features
    Features --> PWAT
    PWAT --> Results["Output (mask PNG, score)"]:::processing

    %% Internal Subsystem Flow
    Checkpoints --> Model
    Model --> Segmentation

    %% Dependency Arrows
    Segmentation --> TF
    Model --> TF
    ImgProc --> OpenCV
    Features --> NumPy
    PWAT --> SKLearn

    %% Configuration & Docs Connections
    Setup --> Pipeline
    Pyproject --> Pipeline
    Requirements --> Pipeline
    Env --> Pipeline
    Docs --> Pipeline
    CI1 --> Pipeline
    CI2 --> Pipeline

    %% Click Events
    click CLI "https://github.com/nico-curti/deepskin/blob/main/deepskin/__main__.py"
    click API "https://github.com/nico-curti/deepskin/blob/main/deepskin/__init__.py"
    click Model "https://github.com/nico-curti/deepskin/blob/main/deepskin/model.py"
    click Checkpoints "https://github.com/nico-curti/deepskin/blob/main/deepskin/checkpoints.py"
    click Segmentation "https://github.com/nico-curti/deepskin/blob/main/deepskin/segmentation.py"
    click ImgProc "https://github.com/nico-curti/deepskin/blob/main/deepskin/imgproc.py"
    click Features "https://github.com/nico-curti/deepskin/blob/main/deepskin/features.py"
    click PWAT "https://github.com/nico-curti/deepskin/blob/main/deepskin/pwat.py"
    click Constants "https://github.com/nico-curti/deepskin/blob/main/deepskin/constants.py"
    click Docs "https://github.com/nico-curti/deepskin/tree/main/docs/"
    click CI1 "https://github.com/nico-curti/deepskin/blob/main/.github/workflows/python.yml"
    click CI2 "https://github.com/nico-curti/deepskin/blob/main/.github/workflows/docs.yml"
    click Setup "https://github.com/nico-curti/deepskin/blob/main/setup.py"
    click Pyproject "https://github.com/nico-curti/deepskin/blob/main/pyproject.toml"
    click Requirements "https://github.com/nico-curti/deepskin/blob/main/requirements.txt"
    click Env "https://github.com/nico-curti/deepskin/blob/main/environment.yml"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#2196F3,color:#0D47A1;
    classDef processing fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef config fill:#CFD8DC,stroke:#455A64,color:#263238;
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef docsci fill:#E0E0E0,stroke:#9E9E9E,color:#424242;
```
