# ihmily/comfyui-light-tool architecture

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

- Interactive diagram: https://gitdiagram.com/ihmily/comfyui-light-tool
- Repository: https://github.com/ihmily/comfyui-light-tool

## Overview

1. **Repository role and boundary**
   - This is a **ComfyUI custom nodes plugin**. It does not define a standalone app; it extends the ComfyUI runtime with reusable nodes for image, text, video, and data handling.
   - The main boundary is between **Python backend nodes** that execute transformations and **small JavaScript UI helpers** that improve node-panel interaction and previews.

2. **Top-level structure**
   - `nodes/` contains the actual node implementations and utility code.
   - `js/` contains frontend scripts for ComfyUI node-panel behavior such as text display and video preview.
   - `demo/` contains a sample workflow JSON and images, showing how the nodes compose in practice.
   - `.github/workflows/` handles release/publishing automation and issue translation automation.

3. **Backend execution model**
   - The core architecture is a set of **ComfyUI node classes** implemented in Python.
   - Each node consumes typed inputs from the ComfyUI graph, performs a local transformation or remote fetch/upload, and returns outputs back into the workflow graph.
   - Most nodes appear to be **stateless utilities** rather than long-running services.

4. **Image-processing subsystem**
   - `nodes/image_crop.py`, `nodes/image_resize.py`, `nodes/image_scale.py`, `nodes/image_upscale.py`, and `nodes/light_tool.py` implement the bulk of the image pipeline.
   - These nodes cover loading, compositing, resizing, scaling, cropping, mask manipulation, channel conversion, transparency handling, and metadata-related image utilities.
   - The data flow is typically: **image tensor / file input → transform → image/mask output** for downstream ComfyUI nodes.

5. **Mask and transparency workflow**
   - Mask-related operations are a distinct subdomain: converting between image and mask, inverting, morphological operations, contour extraction, bounding-box cropping, and transparency extraction.
   - This subsystem supports workflows where **alpha channels and masks are treated as first-class data**, which matters for compositing and foreground/background separation.
   - Several image nodes are clearly designed to preserve or derive transparency-aware outputs.

6. **Text and display subsystem**
   - Text nodes provide simple graph-friendly string handling: input, list assembly, concatenation, replacement, and display.
   - `js/showText.js` and `js/showAnything.js` indicate that some outputs are meant to be **rendered inside the node UI**, not only passed onward as data.
   - This makes the plugin useful as a workflow debugging and annotation layer inside ComfyUI.

7. **Video subsystem**
   - Video-related nodes handle downloading, saving, previewing, and OSS upload.
   - `js/previewVideo.js` supports in-panel preview, while the Python side likely manages path/URL resolution and file persistence.
   - The architecture here crosses a boundary between **remote media URLs, local filesystem storage, and UI preview**.

8. **Data conversion and JSON utilities**
   - `nodes/data_tool.py` covers numeric conversion, arithmetic, hex/RGB conversion, and JSON serialization/deserialization/key-path access.
   - These nodes act as **glue nodes** for graph composition, allowing non-image data to flow through workflows without external scripting.
   - The JSON key-path extractor is especially important for pulling structured values into node graphs.

9. **External service integration**
   - The repo integrates with **Aliyun OSS** through `nodes/oss_tool.py`.
   - OSS upload nodes form a separate integration boundary: local assets or URLs are converted into cloud-hosted resources, often with signed URLs for access.
   - This is the main explicit external infrastructure dependency beyond ordinary HTTP downloads.

10. **Utility and shared code**
   - `nodes/light_tool_utils.py` centralizes helper logic used across multiple node modules.
   - This suggests a shared internal layer for common image/file/mask/encoding helpers rather than duplicating behavior in each node file.
   - `nodes/light_tool.py` appears to be the central aggregation point for the main plugin functionality.

11. **Frontend integration**
   - The `js/` scripts are lightweight and focused on ComfyUI node presentation rather than business logic.
   - They likely bind outputs to custom widgets, enabling rendered text and embedded video previews directly inside the graph editor.
   - This keeps the main data transformation logic in Python while using JavaScript only for UI augmentation.

12. **Packaging and installation**
   - `pyproject.toml` and `requirements.txt` define the Python package/runtime dependencies.
   - The repo is meant to be installed as a **ComfyUI custom_nodes** package via git clone or ComfyUI-Manager.
   - `__init__.py` is the plugin entrypoint that registers nodes and mappings into ComfyUI.

13. **Workflow/demo and release automation**
   - `demo/workflow_demo.json` is an architectural reference for how nodes connect in a real workflow.
   - GitHub Actions in `.github/workflows/` handle publishing/release automation and issue translation, which affects distribution but not runtime behavior.
   - The overall lifecycle is: develop nodes locally, test with ComfyUI workflows, then publish as a custom node package.

14. **What to draw in an architecture diagram**
   - Center the diagram on **ComfyUI graph runtime** with this repo as a plugin layer.
   - Split the plugin into: **Image tools**, **Text tools/UI display**, **Video tools**, **Data/JSON tools**, and **OSS/file integration**.
   - Show Python node modules as the main execution path, JS as UI enhancement, and external arrows to **filesystem, URLs, and Aliyun OSS**.

Main entry points: [`nodes/light_tool.py`](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/light_tool.py) (Light tool), [`nodes/light_tool_utils.py`](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/light_tool_utils.py) (Shared utils), [`nodes/oss_tool.py`](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/oss_tool.py) (OSS upload), [`js/previewVideo.js`](https://github.com/ihmily/comfyui-light-tool/blob/main/js/previewVideo.js) (Video preview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["ComfyUI plugin"]
  node_entrypoint["Plugin entry<br/>node registry<br/>[__init__.py]"]
  node_light_tool["Light tool<br/>node bundle<br/>[light_tool.py]"]
  node_light_utils["Shared utils<br/>helpers"]
end

subgraph group_grp_ui["UI helpers"]
  node_show_text["Text display<br/>ui bridge<br/>[showText.js]"]
  node_show_anything["Output display<br/>ui bridge<br/>[showAnything.js]"]
  node_preview_video["Video preview<br/>ui bridge<br/>[previewVideo.js]"]
end

subgraph group_grp_ops["Workflow tools"]
  node_image_crop["Crop tools<br/>image node set<br/>[image_crop.py]"]
  node_image_resize["Resize tools<br/>image node set<br/>[image_resize.py]"]
  node_image_scale["Scale tools<br/>image node set<br/>[image_scale.py]"]
  node_image_upscale["Upscale tools<br/>image node set<br/>[image_upscale.py]"]
  node_data_tool["Data tools<br/>json and numeric nodes<br/>[data_tool.py]"]
end

subgraph group_grp_infra["Integration and packaging"]
  node_oss_tool["OSS upload<br/>cloud integration<br/>[oss_tool.py]"]
  node_demo_workflow["Demo workflow<br/>sample graph<br/>[workflow_demo.json]"]
  node_requirements["Dependencies<br/>package config<br/>[requirements.txt]"]
  node_pyproject["Package config<br/>build metadata<br/>[pyproject.toml]"]
  node_workflow_release["Release flow<br/>github actions<br/>[publish.yml]"]
  node_workflow_translate["Translate flow<br/>github actions"]
end

node_comfy_runtime["ComfyUI<br/>host runtime"]

node_comfy_runtime -->|"loads"| node_entrypoint
node_entrypoint -->|"registers"| node_light_tool
node_light_tool -->|"uses"| node_light_utils
node_light_tool -->|"includes"| node_image_crop
node_light_tool -->|"includes"| node_image_resize
node_light_tool -->|"includes"| node_image_scale
node_light_tool -->|"includes"| node_image_upscale
node_light_tool -->|"includes"| node_data_tool
node_light_tool -->|"includes"| node_oss_tool
node_image_crop -->|"shares helpers"| node_light_utils
node_image_resize -->|"shares helpers"| node_light_utils
node_image_scale -->|"shares helpers"| node_light_utils
node_image_upscale -->|"shares helpers"| node_light_utils
node_data_tool -->|"shares helpers"| node_light_utils
node_show_text -->|"extends UI"| node_comfy_runtime
node_show_anything -->|"extends UI"| node_comfy_runtime
node_preview_video -->|"extends UI"| node_comfy_runtime
node_oss_tool -->|"returns links"| node_comfy_runtime
node_oss_tool -.->|"may display"| node_show_anything
node_preview_video -.->|"demonstrates"| node_demo_workflow
node_workflow_release -.->|"publishes"| node_pyproject
node_workflow_release -.->|"installs"| node_requirements
node_workflow_translate -.->|"references"| node_demo_workflow

click node_entrypoint "https://github.com/ihmily/comfyui-light-tool/blob/main/__init__.py"
click node_light_tool "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/light_tool.py"
click node_light_utils "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/light_tool_utils.py"
click node_image_crop "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_crop.py"
click node_image_resize "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_resize.py"
click node_image_scale "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_scale.py"
click node_image_upscale "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_upscale.py"
click node_data_tool "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/data_tool.py"
click node_oss_tool "https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/oss_tool.py"
click node_show_text "https://github.com/ihmily/comfyui-light-tool/blob/main/js/showText.js"
click node_show_anything "https://github.com/ihmily/comfyui-light-tool/blob/main/js/showAnything.js"
click node_preview_video "https://github.com/ihmily/comfyui-light-tool/blob/main/js/previewVideo.js"
click node_demo_workflow "https://github.com/ihmily/comfyui-light-tool/blob/main/demo/workflow_demo.json"
click node_requirements "https://github.com/ihmily/comfyui-light-tool/blob/main/requirements.txt"
click node_pyproject "https://github.com/ihmily/comfyui-light-tool/blob/main/pyproject.toml"
click node_workflow_release "https://github.com/ihmily/comfyui-light-tool/blob/main/.github/workflows/publish.yml"
click node_workflow_translate "https://github.com/ihmily/comfyui-light-tool/blob/main/.github/workflows/issue-translator.yml"

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_entrypoint,node_light_tool,node_light_utils toneBlue
class node_show_text,node_show_anything,node_preview_video toneAmber
class node_image_crop,node_image_resize,node_image_scale,node_image_upscale,node_data_tool toneMint
class node_oss_tool,node_demo_workflow,node_requirements,node_pyproject,node_workflow_release,node_workflow_translate toneRose
class node_comfy_runtime toneNeutral
```

## Components

### ComfyUI plugin

Python node implementations registered into the ComfyUI runtime.

- [Plugin entry](https://github.com/ihmily/comfyui-light-tool/blob/main/__init__.py): node registry · Registers the custom nodes and exposes them to ComfyUI. · `__init__.py`
- [Light tool](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/light_tool.py): node bundle · Central aggregation of the main plugin node implementations. · `nodes/light_tool.py`
- [Shared utils](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/light_tool_utils.py): helpers · Common helper logic reused across node modules. · `nodes/light_tool_utils.py`

### UI helpers

Frontend scripts that enhance node output display and previews.

- [Text display](https://github.com/ihmily/comfyui-light-tool/blob/main/js/showText.js): ui bridge · Renders text outputs inside the ComfyUI node UI. · `js/showText.js`
- [Output display](https://github.com/ihmily/comfyui-light-tool/blob/main/js/showAnything.js): ui bridge · Displays generic node outputs in-panel for inspection. · `js/showAnything.js`
- [Video preview](https://github.com/ihmily/comfyui-light-tool/blob/main/js/previewVideo.js): ui bridge · Embeds video preview behavior in the node panel. · `js/previewVideo.js`

### Workflow tools

Core node families for image, text, video, and data manipulation.

- [Crop tools](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_crop.py): image node set · Cropping, contour, transparency, and mask-oriented image operations. · `nodes/image_crop.py`
- [Resize tools](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_resize.py): image node set · Image resizing and related size-adjustment operations. · `nodes/image_resize.py`
- [Scale tools](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_scale.py): image node set · Image scaling and aspect/size transformation nodes. · `nodes/image_scale.py`
- [Upscale tools](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/image_upscale.py): image node set · Upscaling nodes for higher-resolution image output. · `nodes/image_upscale.py`
- [Data tools](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/data_tool.py): json and numeric nodes · Numeric conversion, arithmetic, RGB/hex conversion, and JSON access utilities. · `nodes/data_tool.py`

### Integration and packaging

External service integration, installation metadata, and release automation.

- [OSS upload](https://github.com/ihmily/comfyui-light-tool/blob/main/nodes/oss_tool.py): cloud integration · Aliyun OSS upload and access-link handling for remote assets. · `nodes/oss_tool.py`
- [Demo workflow](https://github.com/ihmily/comfyui-light-tool/blob/main/demo/workflow_demo.json): sample graph · Example ComfyUI workflow showing how the nodes compose. · `demo/workflow_demo.json`
- [Dependencies](https://github.com/ihmily/comfyui-light-tool/blob/main/requirements.txt): package config · Python dependency specification for the plugin. · `requirements.txt`
- [Package config](https://github.com/ihmily/comfyui-light-tool/blob/main/pyproject.toml): build metadata · Project metadata and packaging configuration. · `pyproject.toml`
- [Release flow](https://github.com/ihmily/comfyui-light-tool/blob/main/.github/workflows/publish.yml): github actions · Automation for publishing and issue translation. · `.github/workflows/publish.yml`
- [Translate flow](https://github.com/ihmily/comfyui-light-tool/blob/main/.github/workflows/issue-translator.yml): github actions · Automation for issue translation handling. · `.github/workflows/issue-translator.yml`

### Other components

- **ComfyUI**: host runtime · The host graph engine that executes custom nodes and renders their outputs.

## Connections

- ComfyUI → Plugin entry: loads · ComfyUI imports the plugin entrypoint to register nodes.
- Plugin entry → Light tool: registers · The entrypoint exposes the main node bundle to the host runtime.
- Light tool → Shared utils: uses · Core nodes share common helper routines.
- Light tool → Crop tools: includes · Image cropping and mask utilities are part of the main node set.
- Light tool → Resize tools: includes · Resize operations are exposed through the plugin bundle.
- Light tool → Scale tools: includes · Scaling operations are exposed through the plugin bundle.
- Light tool → Upscale tools: includes · Upscale operations are exposed through the plugin bundle.
- Light tool → Data tools: includes · Data and JSON utilities are part of the plugin bundle.
- Light tool → OSS upload: includes · Cloud upload integration is exposed through the plugin bundle.
- Crop tools → Shared utils: shares helpers · Image modules reuse shared helper code for file/image/mask handling.
- Resize tools → Shared utils: shares helpers · Image modules reuse shared helper code for file/image/mask handling.
- Scale tools → Shared utils: shares helpers · Image modules reuse shared helper code for file/image/mask handling.
- Upscale tools → Shared utils: shares helpers · Image modules reuse shared helper code for file/image/mask handling.
- Data tools → Shared utils: shares helpers · Data utilities rely on shared parsing and conversion helpers.
- Text display → ComfyUI: extends UI · Frontend script augments node rendering inside ComfyUI.
- Output display → ComfyUI: extends UI · Frontend script augments node rendering inside ComfyUI.
- Video preview → ComfyUI: extends UI · Frontend script augments node rendering inside ComfyUI.
- OSS upload → ComfyUI: returns links · Cloud-hosted outputs are fed back into ComfyUI workflows.
- OSS upload → Output display: may display · Uploaded or resolved remote outputs can be shown in-panel.
- Video preview → Demo workflow: demonstrates · The demo workflow illustrates UI preview usage in practice.
- Release flow → Package config: publishes · Release automation uses package metadata for distribution.
- Release flow → Dependencies: installs · Release automation depends on declared Python requirements.
- Translate flow → Demo workflow: references · Automation lives alongside the sample workflow and repo content.