# s0md3v/roop architecture

> Architecture diagram of the GitHub repository s0md3v/roop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/s0md3v/roop
- Repository: https://github.com/s0md3v/roop

## Overview

This archived Stable Diffusion WebUI extension replaces selected target faces with a face from a user-supplied image. The main workflow runs through the WebUI script hooks into the swap engine, which checks target safety, detects faces, applies a selected model, and optionally restores or upscales the result. A separate API exposes image swapping and model listing. The README documents the WebUI workflow and safety behavior; sampled source shows the principal calls, but not every host callback detail.

Main entry points: [`scripts/swapper.py`](https://github.com/s0md3v/roop/blob/main/scripts/swapper.py) (Swap engine), [`scripts/faceswap.py`](https://github.com/s0md3v/roop/blob/main/scripts/faceswap.py) (WebUI script), [`scripts/api.py`](https://github.com/s0md3v/roop/blob/main/scripts/api.py) (Roop API), [`scripts/roop_logging.py`](https://github.com/s0md3v/roop/blob/main/scripts/roop_logging.py) (Logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_webui["WebUI integration"]
  node_webui["WebUI script<br/>[faceswap.py]"]
  node_catalog["Model catalog<br/>[faceswap.py]"]
end

subgraph group_swap["Face replacement"]
  node_engine["Swap engine<br/>[swapper.py]"]
  node_safety["NSFW check<br/>[cimage.py]"]
  node_detector["Face detection<br/>[swapper.py]"]
  node_model["Face-swap model<br/>[swapper.py]"]
  node_enhance["Image enhancement<br/>[swapper.py]"]
end

subgraph group_api["API integration"]
  node_api["Roop API<br/>[api.py]"]
end

subgraph group_support["Runtime support"]
  node_logger["Logger<br/>[roop_logging.py]"]
  node_version["Version display<br/>[roop_version.py]"]
end

node_user(("WebUI user"))
node_sd["Stable Diffusion WebUI"]
node_api_client(("API client"))

node_user -->|"configures"| node_webui
node_sd -->|"runs hooks"| node_webui
node_webui -->|"swaps faces"| node_engine
node_webui -->|"lists models"| node_catalog
node_engine -->|"checks image"| node_safety
node_engine -->|"detects faces"| node_detector
node_engine -->|"loads and applies"| node_model
node_engine -->|"enhances result"| node_enhance
node_engine -->|"logs events"| node_logger
node_webui -->|"logs events"| node_logger
node_api_client -->|"requests swap"| node_api
node_api -->|"lists models"| node_catalog
node_api -->|"swaps faces"| node_engine
node_api -->|"registers callback"| node_sd
node_version -->|"logs version"| node_logger

click node_webui "https://github.com/s0md3v/roop/blob/main/scripts/faceswap.py"
click node_api "https://github.com/s0md3v/roop/blob/main/scripts/api.py"
click node_catalog "https://github.com/s0md3v/roop/blob/main/scripts/faceswap.py"
click node_engine "https://github.com/s0md3v/roop/blob/main/scripts/swapper.py"
click node_safety "https://github.com/s0md3v/roop/blob/main/scripts/cimage.py"
click node_detector "https://github.com/s0md3v/roop/blob/main/scripts/swapper.py"
click node_model "https://github.com/s0md3v/roop/blob/main/scripts/swapper.py"
click node_enhance "https://github.com/s0md3v/roop/blob/main/scripts/swapper.py"
click node_logger "https://github.com/s0md3v/roop/blob/main/scripts/roop_logging.py"
click node_version "https://github.com/s0md3v/roop/blob/main/scripts/roop_version.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webui,node_catalog,node_user,node_sd,node_api_client toneBlue
class node_engine,node_safety,node_detector,node_model,node_enhance toneAmber
class node_api toneMint
class node_logger,node_version toneRose
```

## Components

### WebUI integration

- [WebUI script](https://github.com/s0md3v/roop/blob/main/scripts/faceswap.py): `scripts/faceswap.py`
- [Model catalog](https://github.com/s0md3v/roop/blob/main/scripts/faceswap.py): `scripts/faceswap.py`

### Face replacement

- [Swap engine](https://github.com/s0md3v/roop/blob/main/scripts/swapper.py): `scripts/swapper.py`
- [NSFW check](https://github.com/s0md3v/roop/blob/main/scripts/cimage.py): `scripts/cimage.py`
- [Face detection](https://github.com/s0md3v/roop/blob/main/scripts/swapper.py): `scripts/swapper.py`
- [Face-swap model](https://github.com/s0md3v/roop/blob/main/scripts/swapper.py): `scripts/swapper.py`
- [Image enhancement](https://github.com/s0md3v/roop/blob/main/scripts/swapper.py): `scripts/swapper.py`

### API integration

- [Roop API](https://github.com/s0md3v/roop/blob/main/scripts/api.py): `scripts/api.py`

### Runtime support

- [Logger](https://github.com/s0md3v/roop/blob/main/scripts/roop_logging.py): `scripts/roop_logging.py`
- [Version display](https://github.com/s0md3v/roop/blob/main/scripts/roop_version.py): `scripts/roop_version.py`

### Other components

- **WebUI user**
- **Stable Diffusion WebUI**
- **API client**

## Connections

- WebUI user → WebUI script: configures (evidence: `README.md`)
- Stable Diffusion WebUI → WebUI script: runs hooks (evidence: `README.md`)
- WebUI script → Swap engine: swaps faces (evidence: `scripts/faceswap.py`)
- WebUI script → Model catalog: lists models (evidence: `scripts/faceswap.py`)
- Swap engine → NSFW check: checks image (evidence: `scripts/swapper.py`)
- Swap engine → Face detection: detects faces (evidence: `scripts/swapper.py`)
- Swap engine → Face-swap model: loads and applies (evidence: `scripts/swapper.py`)
- Swap engine → Image enhancement: enhances result (evidence: `scripts/swapper.py`)
- Swap engine → Logger: logs events (evidence: `scripts/swapper.py`)
- WebUI script → Logger: logs events (evidence: `scripts/faceswap.py`)
- API client → Roop API: requests swap (evidence: `scripts/api.py`)
- Roop API → Model catalog: lists models (evidence: `scripts/api.py`)
- Roop API → Swap engine: swaps faces (evidence: `scripts/api.py`)
- Roop API → Stable Diffusion WebUI: registers callback (evidence: `scripts/api.py`)
- Version display → Logger: logs version (evidence: `scripts/roop_version.py`)
