# laogou-666/comfyui-lg_groupexecutor architecture

> Architecture diagram of the GitHub repository laogou-666/comfyui-lg_groupexecutor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laogou-666/comfyui-lg_groupexecutor
- Repository: https://github.com/laogou-666/comfyui-lg_groupexecutor

## Overview

##### 项目类型与目的（从 README + 文件树推断）
这是一个 **ComfyUI 的 custom_nodes 插件/扩展**（Python 后端 + Web 前端 JS），核心目的是：**对“节点组（group）”的执行进行编排与控制**，包括：
- 单组执行信号生成（可重复、可延迟、可串联 signal）
- 执行信号发送到目标组
- 对“执行列表”做重复处理（repeat + 组间延迟）
- 以及 UI/预览相关（README 更新提到 sender 增加 rgba/rgb 预览开关）

它不是独立服务，而是 **嵌入到 ComfyUI 运行时**：依赖 ComfyUI 的图执行引擎、队列、WebSocket 通信、前端节点编辑器。

##### 结构分析（目录/文件对应的架构意义）
- `pyproject.toml`：Python 包/依赖/发布配置（表明可打包分发）
- `__init__.py`：ComfyUI 插件入口（通常用于注册 NODE_CLASS_MAPPINGS、WEB 资源等）
- `.github/workflows/publish.yml`：发布流水线（可在“部署/分发”视图中体现）

##### 后端（Python）
- `py/batch_video.py`：看名字像批处理视频相关（可能是工具模块或复用代码）
- `py/lgutils.py`：通用工具函数（日志、数据结构、通用处理）
- `py/trans.py`：核心业务/信号转换/执行编排逻辑的可能位置（名字更像“trans/transfer/transform”）
> 你画图时可以把它们归为一个 **“GroupExecutor Backend (Python)”** 容器，然后在组件图里再拆成“节点定义/信号模型/队列交互/工具库”。

##### 前端（Web JS）
- `web/groupexecutorUI.js`：UI 侧（节点面板/控件/开关等）
- `web/groupexecutor.js`：核心前端逻辑（节点行为、与后端交互协议）
- `web/groupexecutorsender.js`：Sender 节点前端部分（含预览开关的可能实现点）
- `web/groupexecutorqueuemanager.js`：队列/执行列表管理 UI/状态机（非常关键，建议在图中单列为“Queue Manager”组件）
- `web/queue_utils.js`：队列工具
- `web/value_sender_receiver.js`：值/信号的发送接收（与后端 WebSocket 消息或 ComfyUI 内部事件对应）
- `web/accumulate_preview.js`：预览聚合/累积显示（用于 sender 预览开关的上下游）
> 这些文件表明：插件不仅是新增 Python 节点，还扩展了 ComfyUI 前端编辑器的行为与显示。

##### 建议你画的“最佳系统设计图”应该包含哪些层级（强烈建议至少 3 张）
为了准确且“细分组件”，建议按 C4 思路但不拘泥：

目标：说清这个插件在 ComfyUI 生态中的位置
必须出现的框：
- **User（Workflow 设计者）**
- **Browser (ComfyUI Frontend)**
- **ComfyUI Server（核心：API/WebSocket + Graph Execution Engine + Queue）**
- **Comfyui-LG_GroupExecutor Plugin**
- Backend (Python custom_nodes)
- Frontend (web/*.js)
- 可选外部：文件系统（保存工作流/加载资源）、GPU 推理（ComfyUI 内部通常会调模型推理）

关键箭头（方向要清晰）：
- User → Browser：编辑/点击执行
- Browser ⇄ ComfyUI Server：HTTP + WebSocket（标注“graph updates / execute / status”）
- ComfyUI Server ⇄ Plugin Backend：Python 内部调用/节点执行回调（同进程模块依赖，箭头可标“import/register + node execution callbacks”）
- Browser ⇄ Plugin Frontend：UI 扩展脚本（静态资源加载）
- Plugin Frontend ⇄ ComfyUI Server：通过既有通道发送“执行信号/队列控制/预览数据请求”（具体协议不必写到字段级，但要标“signal messages / queue ops / preview toggles”）

目标：把“前端扩展 vs 后端节点逻辑 vs ComfyUI 核心”拆开
建议容器：
##### ComfyUI Frontend (web app)
- 插件注入的 JS：`groupexecutorUI.js`, `groupexecutor.js`, `...queuemanager.js`, `...sender.js`
##### ComfyUI Backend (Python server)
- 内含：Graph Executor、Prompt/Queue、WebSocket/REST
##### GroupExecutor Plugin Backend (Python package)
- 入口 `__init__.py`（注册节点/注册前端资源）
- 业务模块 `py/trans.py`, `py/lgutils.py`, `py/batch_video.py`
##### （可选）ComfyUI Data/Artifacts
- 工作流 JSON、输出图片/视频、缓存（如果你的系统图要覆盖运行数据）

关系重点：
- “Plugin Backend”不是独立进程，画成 ComfyUI Backend 内的一个“模块/扩展容器”也可以，但要明确它的生命周期跟随 ComfyUI。
- “Plugin Frontend”是被 ComfyUI 前端加载的扩展脚本（静态资源）。

目标：你要“尽可能分组件”，这里是最关键的一张

**后端（Python）组件建议拆分（即使源码没完全展示，也可按职责画）**
- Node Definitions（节点类）
- `GroupExecutorSingle`
- `GroupExecutorSender`
- `GroupExecutorRepeater`
- Signal Model / Payload（执行信号的数据结构）
- Resolution（通过 `group_name` 找到目标节点组/子图）
- Scheduler / Delay Handler（repeat_count、delay_seconds、group_delay 的实现）
- Chain Propagation（signal 串联传递）
- Queue/Execution Bridge（把“信号”转换成 ComfyUI 可执行的队列项/触发执行）
- Utilities（`lgutils.py`）
- (Optional) Batch/Preview helpers（`batch_video.py` 若参与预览/累积）

**前端（Web）组件建议拆分**
- UI Layer：`groupexecutorUI.js`（控件、开关、参数面板）
- Node Behavior Layer：`groupexecutor.js`（节点交互逻辑）
- Sender UI/Preview：`groupexecutorsender.js` + `accumulate_preview.js`（预览累积、rgba/rgb 开关）
- Queue Manager：`groupexecutorqueuemanager.js` + `queue_utils.js`（执行列表、重复处理的 UI/状态）
- Value/Signal Transport：`value_sender_receiver.js`（消息收发、与后端同步）

**组件间箭头建议标注“动作/数据”**
- UI Layer → Node Behavior：用户改参数/点击触发
- Node Behavior → Transport：发送 signal/控制消息
- Transport ⇄ ComfyUI WS/REST：执行、取消、状态更新
- Queue Manager ⇄ Transport：队列状态同步、取消 bug 修复点也在这里（建议加注释说明“cancel path”）
- Preview components ⇄ Transport：预览数据订阅/开关状态下发

##### 场景 S2：链式传递 + Repeater（复杂流程）
- 多个 Single 串联：signal payload 在每一步被扩展（建议在图上写“signal = list of group tasks”）
- Repeater 把执行列表复制 N 次，并在组间插入 delay
- Sender 最终将“flatten 后的任务序列”提交给 queue

##### 场景 S3：取消（README 提到修复取消 bug）
- Frontend QueueManager 触发 cancel
- 通过 WS/REST 调 ComfyUI cancel API
- 后端更新状态，前端同步队列/预览停止
> 这里把“取消路径”单独画出来，能体现你对关键非功能流程的覆盖。

##### 图上要明确标注的技术/框架点（不写会显得图不专业）
- **ComfyUI custom_nodes 插件机制**（`__init__.py` 注册节点/资源）
- **前端扩展 JS 注入**（`web/` 静态资源由 ComfyUI 加载）
- **通信**：ComfyUI 常见为 **HTTP + WebSocket**（图中就写这两个）
- **执行编排要素**：repeat、delay、group_delay、signal chain、queue management
- **数据类型**：signal（执行信号）、execution list（执行列表）、preview frames（预览帧/图像）

##### 元素要求
- 每个框都带：**职责一句话 + 关键文件名**（例如 “Queue Manager (web/groupexecutorqueuemanager.js)”）
- 箭头必须有动词：submit / enqueue / propagate / cancel / preview update
- 对“同进程模块调用”与“网络调用”用不同线型：
- 实线：同进程（ComfyUI backend ↔ plugin backend）
- 虚线：网络（browser ↔ server）

##### 颜色/形状建议（简单但信息密度高）
- 蓝色：ComfyUI Core
- 绿色：Plugin Backend (Python)
- 橙色：Plugin Frontend (JS)
- 灰色：User/外部系统
- 圆柱体：数据存储/工件（workflow json、outputs）

##### 结合该项目“不要过度抽象”的拆分建议（越细越好）
你可以把插件至少拆到以下“可落地”的组件粒度（推荐直接按下面画）：
- Frontend
- GroupExecutor UI
- Sender UI + Preview Toggle (rgba/rgb)
- Preview Accumulator
- Queue Manager
- Transport (Value/Signal sender/receiver)
- Queue Utils
- Backend
- Node: Single
- Node: Repeater
- Node: Sender
- Signal Payload Builder
- Delay/Repeat Scheduler
- Resolver
- Queue/Executor Bridge
- Utilities
- ComfyUI Core（作为依赖边界）
- Graph Runtime / Node Execution
- Prompt/Queue
- WS/REST API
- Preview/Progress events

这样画出来的图会非常“工程可读”：任何人拿到图就能回到对应文件定位实现。

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Context / Ecosystem
  %% =========================
  subgraph "Context (ComfyUI Ecosystem)"
    direction TB

    User["User (Workflow Designer)\n- edits workflow\n- triggers execute/cancel"]:::external

    subgraph "Browser (ComfyUI Frontend Web App)"
      direction TB
      BrowserApp["ComfyUI Frontend\n- node editor\n- renders previews\n- loads custom JS"]:::comfyui
      PluginWeb["GroupExecutor Plugin Frontend (web/*.js)\n- UI + node behaviors\n- queue manager\n- transport + preview"]:::pluginFE
    end

    subgraph "ComfyUI Server (Python Runtime)"
      direction TB
      CoreAPI["WS/REST API Layer\n- execute\n- status/progress\n- cancel"]:::comfyui
      GraphEngine["Graph Execution Engine\n- node execution callbacks\n- group/subgraph runtime"]:::comfyui
      PromptQueue[("Prompt/Queue\n- pending tasks\n- running tasks")]:::db
      PreviewEvents["Preview/Progress Events\n- image frames\n- progress updates"]:::comfyui

      subgraph "Custom Nodes (In-Process Extensions)"
        direction TB
        PluginBE["GroupExecutor Plugin Backend (Python)\n- orchestration\n- signal->queue bridge\n- delay/repeat/chain"]:::pluginBE
      end
    end

    subgraph "Data / Artifacts"
      direction TB
      WorkflowJSON[("Workflow JSON\n(saved/loaded)")]:::db
      Outputs[("Outputs\n(images/videos/cache)")]:::db
    end
  end

  %% =========================
  %% Container view (vertical)
  %% =========================
  subgraph "Containers (Runtime Units)"
    direction TB

    C1["Container: Browser Web App\nComfyUI Frontend + Plugin JS"]:::container
    C2["Container: ComfyUI Backend Server\nAPI + Graph Engine + Queue"]:::container
    C3["Container: Plugin Backend Module\ncustom_nodes package (in-process)"]:::container
    C4["Container: Artifacts Storage\nworkflows + outputs"]:::container
  end

  %% =========================
  %% Component view - Plugin Frontend (JS)
  %% =========================
  subgraph "Plugin Frontend Components (JavaScript)"
    direction TB

    FE_UI["UI Layer\n- panels/controls/toggles"]:::pluginFE
    FE_Node["Node Behavior Layer\n- node interactions\n- protocol glue"]:::pluginFE
    FE_SenderUI["Sender UI + Preview Toggle\n- rgba/rgb switch"]:::pluginFE
    FE_PreviewAcc["Preview Accumulator\n- accumulate/compose preview frames"]:::pluginFE
    FE_QM["Queue Manager\n- execution list UI/state\n- repeat handling\n- cancel path"]:::pluginFE
    FE_QUtils["Queue Utils\n- list ops/helpers"]:::pluginFE
    FE_Transport["Value/Signal Transport\n- send/receive messages\n- sync state"]:::pluginFE
  end

  %% =========================
  %% Component view - Plugin Backend (Python)
  %% =========================
  subgraph "Plugin Backend Components (Python)"
    direction TB

    BE_Entry["Plugin Entry\n- register NODE_CLASS_MAPPINGS\n- register web resources"]:::pluginBE

    subgraph "Node Definitions"
      direction TB
      BE_NodeSingle["Node: GroupExecutorSingle\n- build execution signal\n- repeat/delay params"]:::pluginBE
      BE_NodeRepeater["Node: GroupExecutorRepeater\n- duplicate execution list\n- insert group delays"]:::pluginBE
      BE_NodeSender["Node: GroupExecutorSender\n- submit task sequence\n- preview options"]:::pluginBE
    end

    BE_Signal["Signal Payload Builder/Model\n- execution signal\n- execution list (tasks)"]:::pluginBE
    BE_GroupRes["Group Resolver\n- resolve group_name -> target group/subgraph"]:::pluginBE
    BE_Scheduler["Delay/Repeat Scheduler\n- delay_seconds\n- group_delay\n- repeat_count"]:::pluginBE
    BE_Chain["Chain Propagation\n- compose/extend task list"]:::pluginBE
    BE_Bridge["Queue/Executor Bridge\n- signal -> ComfyUI queue items\n- trigger execution"]:::pluginBE
    BE_Utils["Utilities\n- logging/helpers"]:::pluginBE
    BE_BatchPrev["Batch/Preview Helpers\n- batch video or preview utilities"]:::pluginBE
  end

  %% =========================
  %% DevOps / Packaging
  %% =========================
  subgraph "Packaging & Release"
    direction TB
    RepoMeta["Project Metadata\n- packaging/deps"]:::devops
    CIPublish["CI Workflow\n- build/publish pipeline"]:::devops
    Readme["README\n- usage + architecture hints\n- UI preview toggle notes"]:::doc
  end

  %% =========================
  %% Relationships (Context)
  %% =========================
  User -->|"edit/execute/cancel"| BrowserApp
  BrowserApp -->|"load_plugin_js"| PluginWeb

  BrowserApp -.->|"HTTP/WS:graph_updates/execute/status"| CoreAPI
  PluginWeb -.->|"HTTP/WS:signal_messages/queue_ops/preview_toggles"| CoreAPI

  CoreAPI -->|"dispatch_execute"| GraphEngine
  GraphEngine -->|"enqueue/dequeue"| PromptQueue
  GraphEngine -->|"emit_preview/progress"| PreviewEvents
  PreviewEvents -.->|"WS:preview_update/status"| BrowserApp

  GraphEngine -->|"node_execution_callbacks"| PluginBE
  PluginBE -->|"enqueue/trigger"| PromptQueue

  BrowserApp -->|"save/load"| WorkflowJSON
  GraphEngine -->|"write_outputs"| Outputs

  %% =========================
  %% Relationships (Containers)
  %% =========================
  C1 -.->|"HTTP/WS"| C2
  C2 -->|"in-process_import/register"| C3
  C2 -->|"read/write"| C4

  %% =========================
  %% Relationships (Frontend components)
  %% =========================
  FE_UI -->|"user_actions/update_controls"| FE_Node
  FE_SenderUI -->|"toggle_preview_rgba/rgb"| FE_PreviewAcc
  FE_Node -->|"build_control_messages"| FE_Transport
  FE_QM -->|"queue_state_sync/cancel_requests"| FE_Transport
  FE_QUtils -->|"helpers"| FE_QM
  FE_PreviewAcc -->|"subscribe/render_preview"| FE_Transport
  FE_Transport -.->|"WS/REST:execute/status/cancel"| CoreAPI

  %% =========================
  %% Relationships (Backend components)
  %% =========================
  BE_Entry -->|"register_nodes/resources"| PluginBE
  BE_NodeSingle -->|"create_signal"| BE_Signal
  BE_NodeRepeater -->|"expand_task_list"| BE_Signal
  BE_NodeSender -->|"submit_sequence"| BE_Bridge

  BE_Signal -->|"resolve_targets"| BE_GroupRes
  BE_Signal -->|"apply_repeat/delay"| BE_Scheduler
  BE_Signal -->|"propagate_chain"| BE_Chain
  BE_Chain -->|"final_task_sequence"| BE_Bridge
  BE_Bridge -->|"enqueue_tasks"| PromptQueue

  BE_Utils -->|"log/helpers"| BE_Signal
  BE_BatchPrev -->|"optional_preview_support"| BE_NodeSender

  %% =========================
  %% Key Flows (mini sequence as vertical flow)
  %% =========================
  subgraph "Key Flow S1: Single -> Sender -> Execute Group"
    direction TB
    S1_1["(1) User sets group_name/repeat/delay"]:::flow
    S1_2["(2) Frontend updates node params"]:::flow
    S1_3["(3) Single builds signal (task list)"]:::flow
    S1_4["(4) Sender submits via bridge"]:::flow
    S1_5["(5) ComfyUI enqueues + executes group"]:::flow
    S1_6["(6) WS status + preview update UI"]:::flow
  end
  User --> S1_1 --> FE_UI --> S1_2 --> FE_Node --> FE_Transport
  FE_Transport --> S1_3 --> BE_NodeSingle --> BE_Signal --> S1_4 --> BE_NodeSender --> BE_Bridge --> S1_5 --> GraphEngine --> PreviewEvents -.-> S1_6 --> BrowserApp

  subgraph "Key Flow S3: Cancel (Queue Manager)"
    direction TB
    S3_1["(1) QueueManager triggers cancel"]:::flowCancel
    S3_2["(2) Transport calls cancel API"]:::flowCancel
    S3_3["(3) Backend updates queue state"]:::flowCancel
    S3_4["(4) Frontend sync stops previews"]:::flowCancel
  end
  FE_QM --> S3_1 --> FE_Transport -.-> S3_2 -.-> CoreAPI --> S3_3 --> PromptQueue --> S3_4 --> FE_PreviewAcc

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click BE_Entry "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/__init__.py"
  click RepoMeta "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/pyproject.toml"
  click CIPublish "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/.github/workflows/publish.yml"
  click BE_Signal "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/py/trans.py"
  click BE_Utils "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/py/lgutils.py"
  click BE_BatchPrev "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/py/batch_video.py"
  click FE_Node "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/web/groupexecutor.js"
  click FE_UI "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/web/groupexecutorUI.js"
  click FE_SenderUI "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/web/groupexecutorsender.js"
  click FE_QM "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/web/groupexecutorqueuemanager.js"
  click FE_QUtils "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/web/queue_utils.js"
  click FE_Transport "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/web/value_sender_receiver.js"
  click FE_PreviewAcc "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/web/accumulate_preview.js"
  click Readme "https://github.com/laogou-666/comfyui-lg_groupexecutor/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#e6e6e6,stroke:#666,stroke-width:1px,color:#111
  classDef comfyui fill:#d6ecff,stroke:#2b6cb0,stroke-width:1.2px,color:#0b1f33
  classDef pluginBE fill:#d9f7d9,stroke:#2f855a,stroke-width:1.2px,color:#0f2a1b
  classDef pluginFE fill:#ffe7cc,stroke:#c05621,stroke-width:1.2px,color:#2a1408
  classDef db fill:#f2f2f2,stroke:#4a5568,stroke-width:1.2px,color:#111
  classDef container fill:#f7fafc,stroke:#2d3748,stroke-width:1px,color:#111
  classDef devops fill:#efe6ff,stroke:#6b46c1,stroke-width:1.2px,color:#1f1333
  classDef doc fill:#fff5f5,stroke:#c53030,stroke-width:1.2px,color:#2a0c0c
  classDef flow fill:#f0fff4,stroke:#2f855a,stroke-width:1px,color:#0f2a1b
  classDef flowCancel fill:#fffaf0,stroke:#b7791f,stroke-width:1px,color:#2a1a05
```
