ihmily/comfyui-light-tool

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.