# jax-explorer/comfyui-uno architecture

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

- Interactive diagram: https://gitdiagram.com/jax-explorer/comfyui-uno
- Repository: https://github.com/jax-explorer/comfyui-uno

## Overview

##### Project Type & Purpose
- This is an open-source ComfyUI node collection written in Python to expose UNO-based diffusion pipelines as visual nodes.
- Purpose: let ComfyUI users load UNO models, configure sampling, and generate images with subject-driven control.

##### File Structure
- Top-level:
- nodes/             ← ComfyUI node definitions (comfy_nodes.py)
- uno/               ← UNO “flux” library: pipeline, modules, model, sampling, util
- uno/utils/         ← helper scripts (e.g., YAML→args conversion)
- asset/             ← static assets (e.g., screenshots)
- workflow/          ← example workflow JSON for ComfyUI
- requirements.txt, README.md, LICENSE
- Pattern: plugin layers (nodes/) call into a self-contained inference library (uno/flux/…).
- Config/deployment: requirements.txt pins PyPI deps; workflow/*.json demonstrates runtime wiring.

##### Extract README Insights
- Core stack: Python, PyTorch (flux modules), ComfyUI.
- External services: HuggingFace (model download), optional ComfyOnline for cloud execution.
- Features: FP8 support, offload, automatic model fetching.

##### Main Components & Interactions
a. Components:
1. User Interface: ComfyUI host application (web or desktop).
2. Node Plugin: nodes/comfy_nodes.py defines custom graph nodes.
3. Inference Library: uno/flux (pipeline.py, sampling.py, model.py, modules/…).
4. Model Storage: local “models/…” directories & HuggingFace hub.
5. Runtime Environment: Python interpreter, GPU (CUDA/FP8), optional CPU offload.
6. Utilities: YAML-to-args converter, workflow JSON loader.
7. (Optional) ComfyOnline Cloud Service.
b. Interactions:
- ComfyUI UI → invokes Node Plugin
- Node Plugin → calls UNO Pipeline API
- Pipeline → loads model weights (from local cache or HuggingFace)
- Pipeline → passes data through modules (autoencoder, conditioner, layers)
- Sampling component → performs diffusion steps on GPU/CPU
- Output images → returned back to ComfyUI UI
- Utilities handle config conversion and workflow import/export
- (If using ComfyOnline) UI/API calls ComfyOnline endpoints, which run the same code server-side.
c. Architectural Patterns & Principles:
- Plugin Architecture: nodes/ extends ComfyUI core without modifying it.
- Modular Design: uno/flux broken into pipeline, sampling, model, util, modules.
- Separation of Concerns: UI layer vs. orchestration layer vs. low-level model ops.
- Lazy Loading & Offload: optional CPU offload for memory optimization.
d. Key Technologies:
- Python 3.x
- PyTorch (flux modules)
- ComfyUI framework
- HuggingFace model hub
- YAML for config
- JSON workflow definitions

##### Detailed Elements
- ComfyUI Host
- Node Definitions (nodes/comfy_nodes.py)
- Flux Pipeline & Modules (uno/flux/*.py)
- Sampling Engine
- Model Sources (local vs. HuggingFace)
- GPU/CPU Offload
- Config Conversion Utility
- Example Workflow Loader (workflow/flux-uno.json)
- Optional Cloud Service (ComfyOnline)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        UI["ComfyUI Host"]:::ui
        Online["ComfyOnline Cloud Service"]:::external
    end

    %% Plugin Layer
    subgraph "Plugin Layer"
        direction TB
        NodePlugin["Node Plugin\n(nodes/comfy_nodes.py)"]:::plugin
    end

    %% Inference Library
    subgraph "Inference Library"
        direction TB
        Pipeline["Flux Pipeline\n(uno/flux/pipeline.py)"]:::inference
        Sampling["Sampling Engine\n(uno/flux/sampling.py)"]:::inference
        ModelIF["Model Interface\n(uno/flux/model.py)"]:::inference
        MathUtil["Flux Math Utils\n(uno/flux/math.py)"]:::inference
        subgraph "Modules"
            direction TB
            AE["Autoencoder\n(uno/flux/modules/autoencoder.py)"]:::module
            Cond["Conditioner\n(uno/flux/modules/conditioner.py)"]:::module
            Layers["Layers\n(uno/flux/modules/layers.py)"]:::module
        end
        Util["Flux Utility Functions\n(uno/flux/util.py)"]:::inference
    end

    %% Storage & External Services
    subgraph "Model Storage & External"
        direction TB
        LocalModels["Local Model Cache"]:::storage
        HFHub["HuggingFace Hub"]:::external
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        direction TB
        GPU["GPU (CUDA/FP8)"]:::runtime
        CPU["CPU Offload"]:::runtime
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        YAMLConv["YAML-to-Args Converter\n(uno/utils/convert_yaml_to_args_file.py)"]:::util
        WorkflowLoader["Example Workflow Loader\n(workflow/flux-uno.json)"]:::util
    end

    %% Project Files
    subgraph "Project Files"
        direction TB
        Assets["Static Assets\n(asset/)"]:::files
        Req["requirements.txt"]:::files
        Readme["README.md"]:::files
    end

    %% Connections
    UI -->|invokes| NodePlugin
    UI -->|optional API calls| Online
    Online -->|runs nodes server-side| Pipeline

    NodePlugin -->|calls| Pipeline
    NodePlugin -->|uses config| YAMLConv
    NodePlugin -->|loads workflow| WorkflowLoader

    Pipeline -->|loads weights| LocalModels
    Pipeline -->|downloads if missing| HFHub
    Pipeline -->|interfaces| ModelIF
    Pipeline -->|uses maths| MathUtil
    Pipeline -->|dispatches modules| AE
    Pipeline -->|dispatches modules| Cond
    Pipeline -->|dispatches modules| Layers
    Pipeline -->|calls| Sampling
    Pipeline -->|utility| Util

    Sampling -->|executes on| GPU
    Sampling -->|offload to| CPU

    %% Click Events
    click NodePlugin "https://github.com/jax-explorer/comfyui-uno/blob/main/nodes/comfy_nodes.py"
    click Pipeline "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/pipeline.py"
    click Sampling "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/sampling.py"
    click ModelIF "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/model.py"
    click MathUtil "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/math.py"
    click AE "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/modules/autoencoder.py"
    click Cond "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/modules/conditioner.py"
    click Layers "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/modules/layers.py"
    click Util "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/flux/util.py"
    click YAMLConv "https://github.com/jax-explorer/comfyui-uno/blob/main/uno/utils/convert_yaml_to_args_file.py"
    click WorkflowLoader "https://github.com/jax-explorer/comfyui-uno/blob/main/workflow/flux-uno.json"
    click Assets "https://github.com/jax-explorer/comfyui-uno/tree/main/asset/"
    click Req "https://github.com/jax-explorer/comfyui-uno/blob/main/requirements.txt"
    click Readme "https://github.com/jax-explorer/comfyui-uno/blob/main/README.md"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef plugin fill:#A9DFBF,stroke:#196F3D,color:#0E6251;
    classDef inference fill:#F5B041,stroke:#B9770E,color:#1B2631;
    classDef module fill:#F8C471,stroke:#B9770E,color:#1B1B1B;
    classDef external fill:#D7BDE2,stroke:#6C3483,color:#1B1B1B;
    classDef storage fill:#AED6F1,stroke:#1B4F72,color:#1B1B1B;
    classDef runtime fill:#F1948A,stroke:#C0392B,color:#1B1B1B;
    classDef util fill:#D5D8DC,stroke:#566573,color:#1B1B1B;
    classDef files fill:#D6EAF8,stroke:#2E86C1,color:#1B1B1B;
```
