ComfyUI Architecture Overview: Initialization, Node System, Execution Flow, Cache Mechanism and Usage Limits

1. ComfyUI Initialization and Execution Process

ComfyUI is an open‑source AI drawing tool built on Stable Diffusion that uses a modular, node‑based workflow, allowing users to construct complex image‑generation pipelines through intuitive drag‑and‑drop operations.

1.1 System Initialization

The startup sequence consists of three main phases: pre‑startup script execution, node system initialization, and server/WebSocket setup.

1. Pre‑startup preparation

def execute_prestartup_script():
    # Execute custom node pre‑startup scripts
    for custom_node_path in node_paths:
        if os.path.exists(script_path):
            execute_script(script_path)

2. Node system initialization

def init_extra_nodes():
    # Load built‑in nodes
    import_failed = init_builtin_extra_nodes()
    # Load custom nodes
    init_external_custom_nodes()

Built‑in nodes reside in the comfy_extras directory, while user‑defined nodes are placed in custom_nodes and loaded dynamically.

3. Server initialization

class PromptServer:
    def __init__(self, loop):
        # Initialize Web server
        self.app = web.Application()
        # Initialize WebSocket
        self.sockets = dict()
        # Initialize execution queue
        self.prompt_queue = None

1.2 Workflow Execution Process

The execution pipeline follows these key steps:

Workflow validation – checks node types, connections, and input conformity.

Execution preparation – creates a DynamicPrompt object and initializes caches.

Node execution – retrieves inputs, checks caches, runs node logic, and stores results.

Result caching – avoids redundant computation.

Returning outputs – feeds results to downstream nodes or the UI.

Validation example:

def validate_prompt(prompt):
    # 1. Verify node types exist
    # 2. Verify at least one output node
    # 3. Verify node inputs
    return (valid, error, good_outputs, node_errors)

Execution preparation example:

def execute(self, prompt, prompt_id, extra_data={}, execute_outputs=[]):
    # 1. Initialize execution environment
    with torch.inference_mode():
        # 2. Create dynamic prompt
        dynamic_prompt = DynamicPrompt(prompt)
        # 3. Initialize cache
        is_changed_cache = IsChangedCache(dynamic_prompt, self.caches.outputs)

Node execution core logic:

def execute(server, dynprompt, caches, current_item, extra_data, executed, prompt_id, execution_list, pending_subgraph_results):
    # 1. Retrieve node information
    unique_id = current_item
    inputs = dynprompt.get_node(unique_id)['inputs']
    class_type = dynprompt.get_node(unique_id)['class_type']
    # 2. Check cache
    if caches.outputs.get(unique_id) is not None:
        return (ExecutionResult.SUCCESS, None, None)
    # 3. Get input data
    input_data_all, missing_keys = get_input_data(inputs, class_def, unique_id, caches.outputs, dynprompt, extra_data)
    # 4. Execute node
    output_data, output_ui, has_subgraph = get_output_data(obj, input_data_all)
    # 5. Cache result
    caches.ui.set(unique_id, {...})
    return (ExecutionResult.SUCCESS, output_data, output_ui)

1.3 Execution Queue Management

ComfyUI uses a prompt worker that pulls tasks from a queue, executes them via PromptExecutor , and performs resource cleanup when needed.

def prompt_worker(q, server):
    e = execution.PromptExecutor(server, lru_size=args.cache_lru)
    while True:
        # 1. Get queue task
        queue_item = q.get(timeout=timeout)
        # 2. Execute prompt
        e.execute(item[2], prompt_id, item[3], item[4])
        # 3. Resource management
        if need_gc:
            comfy.model_management.cleanup_models()
            gc.collect()

1.4 Cache System

ComfyUI employs a hierarchical cache that stores node outputs, UI data, and large objects to improve performance.

class HierarchicalCache:
    def __init__(self):
        self.outputs = {}  # Node output cache
        self.ui = {}       # UI related cache
        self.objects = {}  # Large object cache

Cache types:

outputs : caches node results.

ui : caches UI‑related information such as previews.

objects : caches heavyweight objects like models.

1.5 Resource Management and Error Handling

During workflow execution the system automatically clears unused models, performs garbage collection, and captures execution errors to report them to the UI.

# Memory cleanup
comfy.model_management.cleanup_models()
gc.collect()

# Model unload
comfy.model_management.unload_all_models()

# Cache cleanup
cache.clean_unused()

Error handling example:

def handle_execution_error(self, prompt_id, prompt, current_outputs, executed, error, ex):
    # Handle interrupt exception
    if isinstance(ex, comfy.model_management.InterruptProcessingException):
        self.add_message("execution_interrupted", mes)
    else:
        self.add_message("execution_error", mes)

2. Node System Architecture

The node system is the core of ComfyUI, designed in Python with each node defined as a class containing INPUT_TYPES , RETURN_TYPES , FUNCTION , and CATEGORY attributes.

Node mappings are stored in:

NODE_CLASS_MAPPINGS = {}
NODE_DISPLAY_NAME_MAPPINGS = {}

Two node categories exist:

Built‑in nodes – located in comfy_extras , providing common image operations.

Custom nodes – placed in custom_nodes and loaded at runtime via dynamic module import.

Custom node loading example:

def load_custom_node(module_path: str, ignore=set(), module_parent="custom_nodes") -> bool:
    module_spec = importlib.util.spec_from_file_location(module_name, module_path)
    module = importlib.util.module_from_spec(module_spec)
    if hasattr(module, "NODE_CLASS_MAPPINGS"):
        for name, node_cls in module.NODE_CLASS_MAPPINGS.items():
            NODE_CLASS_MAPPINGS[name] = node_cls
    return True

2.2 Node Execution Engine

The PromptExecutor class in execution.py orchestrates node execution, handling input validation, function calls, caching, and output delivery.

class PromptExecutor:
    def execute(self, prompt, prompt_id, extra_data=None, execute_outputs=[]):
        # Core node execution logic
        ...

2.3 Cache Mechanism

ComfyUI supports both classic hierarchical caching and LRU caching. The CacheSet class initializes the appropriate strategy based on the lru_size parameter.

class CacheSet:
    def __init__(self, lru_size=None):
        if lru_size is None or lru_size == 0:
            self.init_classic_cache()
        else:
            self.init_lru_cache(lru_size)
        self.all = [self.outputs, self.ui, self.objects]

Classic cache initialization:

def init_classic_cache(self):
    self.outputs = HierarchicalCache(CacheKeySetInputSignature)
    self.ui = HierarchicalCache(CacheKeySetInputSignature)
    self.objects = HierarchicalCache(CacheKeySetID)

LRU cache initialization:

def init_lru_cache(self, cache_size):
    self.outputs = LRUCache(CacheKeySetInputSignature, max_size=cache_size)
    self.ui = LRUCache(CacheKeySetInputSignature, max_size=cache_size)
    self.objects = HierarchicalCache(CacheKeySetID)

2.4 Data Flow and Dependency Management

ComfyUI parses JSON‑encoded node graphs, automatically resolves dependencies, and constructs an execution order that avoids cycles and deadlocks.

2.5 Front‑end Interface

Real‑time communication uses WebSocket endpoints, while REST APIs provide node information and other non‑real‑time queries.

@routes.get('/ws')
async def websocket_handler(request):
    # Handle front‑end connection, send execution status, receive commands
    ...

@routes.get("/object_info/{node_class}")
async def get_object_info_node(request):
    # Retrieve node details
    ...

3. Cache System Details

The cache consists of three types – outputs , ui , and objects – each managed by either a classic hierarchical cache or an LRU cache.

Cache key strategies:

CacheKeySetInputSignature for outputs and ui , based on node input signatures.

CacheKeySetID for objects , based on node IDs.

Cache cleanup is performed automatically; LRU caches use a generation counter to evict the least‑recently‑used items.

4. Usage Limits

While ComfyUI does not impose a hard limit on node count, several practical constraints exist:

Maximum history size: MAXIMUM_HISTORY_SIZE = 10000 .

Maximum image resolution: MAX_RESOLUTION = 16384 (pixels).

VAE tile size range: 128–4096 pixels (step 32).

Upload size controlled by max_upload_size command‑line argument.

Cache size governed by the optional LRU size parameter.

Execution queue serializes node execution to avoid performance bottlenecks.

CLIP tokenizer maximum length: model_max_length = 77 tokens.

Best practices include keeping workflows concise, monitoring memory/GPU usage, splitting large workflows into sub‑workflows, and adjusting configuration parameters to match available resources.

5. Modular Design Benefits

The modular node architecture of ComfyUI lowers the technical barrier for AI image generation, enabling users to quickly prototype and customize pipelines, while the extensible cache and plugin system provide a solid foundation for future development and community contributions.