# gourieff/comfyui-reactor architecture

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

- Interactive diagram: https://gitdiagram.com/gourieff/comfyui-reactor
- Repository: https://github.com/gourieff/comfyui-reactor

## Overview

##### Project Type and Purpose
- This is a Python-based plugin (extension) for ComfyUI—a node-based workflow engine for AI image processing—providing nodes that perform face swapping, face model creation, masking and restoration.
- It’s not a web application or microservice. It’s a modular plugin that hooks into ComfyUI’s node registry and execution engine, invoking deep-learning models (ONNX, PyTorch) for detection, swapping, restoration and related utilities.

##### High-Level Component Analysis
- ComfyUI Core
- Web UI (browser front-end)
- Node Execution Engine (Python backend)
- ReActor Extension (loaded as “custom_nodes/ComfyUI-ReActor”)
- Node Registration Layer (nodes.py)
- Pipeline Modules (modules/*.py)
- Face‐swap Logic & Utilities (reactor_utils.py, reactor_patcher.py)
- Third-Party Integration Libraries
- BasicSR integration (r_basicsr package: archs, data loaders, losses, metrics, models, ops)
- InsightFace / ONNX models for face detection & embeddings (r_facelib)
- Chainner architectures for face model blending (r_chainner)
- CLI / Installer
- install.py / install.bat
- scripts/ directory with sub-folders for architecture scripts, masking, boosting, etc.
- External Model Repositories
- HuggingFace downloads (inswapper_128.onnx, buffalo_l, face-restorers models, SAM, YOLO face detector)

##### Data Flow & Interactions
- User drags “ReActorFaceSwap” node into a ComfyUI workflow in the browser → ComfyUI registers it via nodes.py → on execution:
1. The node calls reactor_utils, which invokes:
a. Face detection (r_facelib → ONNX detectors or ultralytics)
b. Face embedding extraction (r_facelib → inswapper_128.onnx)
c. Face swap algorithm (r_chainner + shader scripts)
2. If restoration is enabled, it calls BasicSR models (r_basicsr) to enhance the swapped faces:
- Model architectures (r_basicsr/archs/*)
- Data transforms, degradations (r_basicsr/data)
- Inference ops via PyTorch/CUDA or ONNXRuntime
3. Final compositing and masking (modules/scripts_postprocessing.py)
4. The resulting image is returned to ComfyUI for further chaining or display.

##### Architectural Patterns & Design Principles
- Plugin Architecture: ComfyUI discovers and loads custom_nodes dynamically.
- Modular Node Graph: Each face‐swap/restore/mask operation is encapsulated in its own node module under modules/.
- Separation of Concerns:
- Detection & Embedding (r_facelib)
- Swapping & Blending (r_chainner)
- Super-resolution & Restoration (r_basicsr)
- Orchestration & Compositing (modules/ & reactor_utils)
- Dependency Injection: Nodes declare inputs/outputs so ComfyUI composes pipelines declaratively.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ComfyUI Core
    subgraph "ComfyUI Core" 
        direction TB
        UI["Browser UI"]:::core
        CoreEngine["Node Execution Engine"]:::core
    end

    %% ReActor Extension
    subgraph "ReActor Extension" 
        direction TB
        NodeReg["Node Registration (nodes.py)"]:::extension
        ModuleLayer["Module Layer (modules/)"]:::extension
        UtilLayer["Utility Layer"]:::extension
        ScriptsColl["Scripts Collection (scripts/)"]:::extension
        Installer["CLI / Installer"]:::extension
    end

    %% Third-Party ML Libraries
    subgraph "Third-Party ML Libraries"
        direction TB
        r_facelib["r_facelib (Face Detection & Embedding)"]:::ml
        r_chainner["r_chainner (Face Blending)"]:::ml
        r_basicsr["r_basicsr (Super-Resolution & Restoration)"]:::ml
        ONNXRuntime["ONNXRuntime / PyTorch"]:::ml
    end

    %% Model Storage & External
    subgraph "Model Files & Repos"
        direction TB
        HF["HuggingFace Models"]:::storage
        SavedModels["Saved Face Models\n(models/reactor/faces)"]:::storage
    end

    %% Data Flow
    UI -->|"drag node"| NodeReg
    NodeReg -->|"register nodes"| CoreEngine
    CoreEngine -->|"execute ReActor node"| ModuleLayer
    ModuleLayer -->|"call utilities"| UtilLayer
    UtilLayer -->|"detect & embed"| r_facelib
    r_facelib -->|"use ONNX models"| ONNXRuntime
    UtilLayer -->|"swap faces"| r_chainner
    r_chainner -->|"load architectures"| ONNXRuntime
    ModuleLayer -->|"post-processing"| ScriptsColl
    ScriptsColl -->|"optional restore"| r_basicsr
    r_basicsr -->|"use BasicSR models"| ONNXRuntime
    r_basicsr --> SavedModels
    r_facelib --> HF
    r_chainner --> HF
    r_basicsr --> HF
    ModuleLayer --> CoreEngine
    CoreEngine --> UI

    %% Click Events
    click NodeReg "https://github.com/gourieff/comfyui-reactor/blob/main/nodes.py"
    click ModuleLayer "https://github.com/gourieff/comfyui-reactor/tree/main/modules/"
    click UtilLayer "https://github.com/gourieff/comfyui-reactor/blob/main/reactor_utils.py"
    click UtilLayer "https://github.com/gourieff/comfyui-reactor/blob/main/reactor_patcher.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/tree/main/scripts/"
    click Installer "https://github.com/gourieff/comfyui-reactor/blob/main/install.py"
    click Installer "https://github.com/gourieff/comfyui-reactor/blob/main/install.bat"
    click HF "https://github.com/gourieff/comfyui-reactor/blob/main/inswapper_128.onnx"
    click r_basicsr "https://github.com/gourieff/comfyui-reactor/tree/main/r_basicsr/archs/"
    click r_basicsr "https://github.com/gourieff/comfyui-reactor/tree/main/r_basicsr/data/"
    click r_basicsr "https://github.com/gourieff/comfyui-reactor/tree/main/r_basicsr/losses/"
    click r_basicsr "https://github.com/gourieff/comfyui-reactor/tree/main/r_basicsr/metrics/"
    click r_basicsr "https://github.com/gourieff/comfyui-reactor/tree/main/r_basicsr/models/"
    click r_basicsr "https://github.com/gourieff/comfyui-reactor/tree/main/r_basicsr/ops/"
    click r_basicsr "https://github.com/gourieff/comfyui-reactor/tree/main/r_basicsr/utils/"
    click r_facelib "https://github.com/gourieff/comfyui-reactor/tree/main/r_facelib/detection/retinaface/"
    click r_facelib "https://github.com/gourieff/comfyui-reactor/tree/main/r_facelib/detection/yolov5face/"
    click r_facelib "https://github.com/gourieff/comfyui-reactor/tree/main/r_facelib/parsing/"
    click r_facelib "https://github.com/gourieff/comfyui-reactor/tree/main/r_facelib/utils/"
    click r_chainner "https://github.com/gourieff/comfyui-reactor/tree/main/r_chainner/archs/face/"
    click r_chainner "https://github.com/gourieff/comfyui-reactor/blob/main/r_chainner/model_loading.py"
    click r_chainner "https://github.com/gourieff/comfyui-reactor/blob/main/r_chainner/types.py"
    click ModuleLayer "https://github.com/gourieff/comfyui-reactor/blob/main/modules/images.py"
    click ModuleLayer "https://github.com/gourieff/comfyui-reactor/blob/main/modules/processing.py"
    click ModuleLayer "https://github.com/gourieff/comfyui-reactor/blob/main/modules/scripts.py"
    click ModuleLayer "https://github.com/gourieff/comfyui-reactor/blob/main/modules/scripts_postprocessing.py"
    click ModuleLayer "https://github.com/gourieff/comfyui-reactor/blob/main/modules/shared.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/reactor_faceswap.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/reactor_swapper.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/reactor_sfw.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/reactor_logger.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/reactor_version.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/r_archs/codeformer_arch.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/r_archs/vqgan_arch.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/r_faceboost/restorer.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/r_faceboost/swapper.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/r_masking/core.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/r_masking/segs.py"
    click ScriptsColl "https://github.com/gourieff/comfyui-reactor/blob/main/scripts/r_masking/subcore.py"

    %% Styles
    classDef core fill:#cccccc,stroke:#333,stroke-width:1px
    classDef extension fill:#cce5ff,stroke:#2a5dab,stroke-width:1px
    classDef ml fill:#d4edda,stroke:#2f6627,stroke-width:1px
    classDef storage fill:#ffeeba,stroke:#8a6d1b,stroke-width:1px
```
