# raykosan/comfyui_raykostudio architecture

> Architecture diagram of the GitHub repository raykosan/comfyui_raykostudio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raykosan/comfyui_raykostudio
- Repository: https://github.com/raykosan/comfyui_raykostudio

## Overview

#### Purpose and Host Integration
ComfyUI_RaykoStudio is a Python custom-node extension for ComfyUI, focused on interactive image editing, masking, compositing, prompt/model management, latent preparation, and workflow-aware export. It is installed under ComfyUI’s `custom_nodes` directory and runs inside ComfyUI’s Python server plus browser canvas runtime. Node registration and extension loading originate at `__init__.py`; server-side settings endpoints are implemented in `settings_manager_api.py`.

#### Extension Architecture
The repository is organized as mostly independent Python node implementations paired with optional browser-side custom widgets. Python nodes consume and produce ComfyUI-native values such as `IMAGE` tensors, `MASK`, `LATENT`, `CONDITIONING`, `MODEL`, `CLIP`, and `VAE`; frontend modules render controls and synchronize node/widget state through ComfyUI. Key pairing examples:
- Interactive collage: `Rayko_Collage.py` + `web/rs_collage.js`
- Interactive outpainting: `Rayko_Outpaint.py` + `web/rs_outpaint.js`
- Image adjustments: `Rayko_Adjustments.py` + `web/rs_adjustments.js`

#### Interactive Editing and Queue-Gating Nodes
A defining capability is nodes that pause ComfyUI workflow execution until the user accepts or cancels an edit. These bridge backend processing with persistent frontend editing state and require heartbeat/cleanup behavior to avoid stalled queues.
- Cropping and reinsertion: `Rayko_Crop_Image.py`, `Rayko_Insert_Crop.py`, `web/rs_crop.js`
- Spline mask workflows: `Rayko_Spline_Mask.py`, `Rayko_Intermediate_Spline_Mask.py`, `web/spline_mask.js`
- Batch image selection: `Rayko_Image_Selector.py`, `web/image_selector.js`
- Canvas-based compositing/outpainting: `Rayko_Collage.py`, `Rayko_Outpaint.py`, `web/rs_outpaint.js`

Control flow is: image tensor enters node → backend exposes preview/result state → browser collects edits/approval → backend resumes and emits transformed image, mask, dimensions, or crop metadata.

#### Image Processing, Composition, and Export
Core image-oriented nodes handle alpha preservation, transforms, visual comparison, text rendering, adjustments, and workflow-preserving output.
- Adjustment and color pipeline: `Rayko_Adjustments.py`, `Rayko_Color_Picker.py`, `Rayko_RGB2RGBA.py`
- Text and image composition: `Rayko_Text_Overlay_Pro.py`, `Rayko_Image_Text .py`, `Rayko_Collage.py`
- Output/persistence: `Rayko_Save_Image.py`, `Rayko_Save_Image_Pair.py`
- Input and batch ingestion: `Rayko_Load_Images_From_Dir.py`, `Rayko_Spline_Mask.py`

The runtime uses Torch tensors, Pillow, NumPy, OpenCV, SciPy, FreeType, and Cairo. `Rayko_Text_Overlay_Pro.py` uses bundled font assets under `fonts/` for server-side high-quality rendering.

#### Generative Model and Latent Pipeline
Model-facing nodes prepare ComfyUI generation inputs rather than running a standalone inference service.
- Unified model/LoRA loading: `Rayko_Models_Loader.py`, `Rayko_LoRA Loader.py`
- Image/reference encoding: `Rayko_Image_To_Latent.py`, `Rayko_Ref2Latent.py`
- Empty latent construction: `Rayko_MultiLatent.py`
- Prompt and style construction: `Rayko_Prompts.py`, `Rayko_Styles_Loader.py`

These components load ComfyUI-managed UNET/CLIP/VAE/LoRA assets, encode images via a supplied VAE, and pass latents or modified conditioning downstream to samplers. Styles are repository data in `styles/`; custom fonts are data in `fonts/`.

#### Workflow Control and UI Extensions
Graph-level orchestration is implemented through specialized nodes and frontend behavior:
- Dynamic type-agnostic routing: `Rayko_Any_Switch.py`, `web/rs_any_switch.js`
- Bypass management: `Rayko_Bypass.py`, `web/rs_bypass.js`
- Iterative integer sequencing: `Rayko_Loop_Switch.py`, `web/loopSwitchSeed.js`
- Settings backup/restore extension: `settings_manager_api.py`, `web/settings_manager.js`

The settings manager is distinct from node execution: it accesses ComfyUI interface settings, stores backups outside the repository/ComfyUI tree, and can restart the Python server via server-side process control.

#### External Boundaries and Assets
The primary infrastructure dependency is a compatible ComfyUI installation with Python, Torch, and CUDA-capable execution where applicable. Browser-side JavaScript relies on ComfyUI’s frontend APIs and browser permissions for file/clipboard interactions. LoRA/model metadata can be fetched from the external Civitai API and cached locally by the model-loading nodes. Example workflows are distributable ComfyUI JSON graphs under `Example/`, including `Example/RS Collage.json` and `Example/RS Outpaint New.json`.

Main entry points: [`__init__.py`](https://github.com/raykosan/comfyui_raykostudio/blob/main/__init__.py) (Extension registration), [`Rayko_Crop_Image.py`](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Crop_Image.py) (Queue-gated editing nodes), [`Rayko_Adjustments.py`](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Adjustments.py) (Image processing), [`web/rs_crop.js`](https://github.com/raykosan/comfyui_raykostudio/blob/main/web/rs_crop.js) (Editing widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["ComfyUI Host"]
  node_comfyui{{"ComfyUI server &amp; canvas<br/>host runtime"}}
  node_registration["Extension registration<br/>node loader<br/>[__init__.py]"]
  node_native_types["ComfyUI native values<br/>tensor &amp; model types"]
end

subgraph group_interactive["Interactive Editing"]
  node_interactive_nodes["Queue-gated editing nodes<br/>Python nodes"]
  node_crop_reinsert["Crop reinsertion<br/>Python node"]
  node_editing_widgets["Editing widgets<br/>browser modules<br/>[rs_crop.js]"]
  node_collage_node["Collage compositor<br/>Python node<br/>[Rayko_Collage.py]"]
  node_outpaint_widget["Outpaint widget<br/>browser module<br/>[rs_outpaint.js]"]
end

subgraph group_generation["Generation Inputs"]
  node_model_loader["Model &amp; LoRA loader<br/>Python nodes"]
  node_civitai{{"Civitai API<br/>external metadata API"}}
  node_prompt_styles["Prompts &amp; styles<br/>Python nodes<br/>[Rayko_Prompts.py]"]
  node_style_assets["Style data<br/>repository data"]
  node_latent_prep["Latent preparation<br/>Python nodes"]
end

subgraph group_output["Image Output"]
  node_image_processing["Image processing<br/>Python nodes"]
  node_font_assets["Bundled fonts<br/>rendering assets"]
  node_ingestion["Image ingestion<br/>Python nodes"]
  node_image_export["Image export<br/>Python nodes"]
end

subgraph group_control["Workflow Control"]
  node_workflow_nodes["Routing &amp; bypass nodes<br/>Python nodes"]
  node_workflow_widgets["Workflow widgets<br/>browser modules<br/>[rs_any_switch.js]"]
  node_settings_api["Settings manager API<br/>server API"]
  node_settings_widget["Settings manager UI<br/>browser module"]
  node_example_workflows["Example workflows<br/>ComfyUI JSON graphs"]
end

node_comfyui -->|"loads"| node_registration
node_registration -->|"registers"| node_interactive_nodes
node_registration -->|"registers"| node_image_processing
node_registration -->|"registers"| node_model_loader
node_registration -->|"registers"| node_workflow_nodes
node_registration -->|"exposes"| node_settings_api
node_comfyui -->|"loads frontend extension"| node_editing_widgets
node_comfyui -->|"loads frontend extension"| node_workflow_widgets
node_comfyui -->|"loads frontend extension"| node_settings_widget
node_native_types -->|"image and mask inputs"| node_interactive_nodes
node_interactive_nodes -->|"preview, edit state, approval"| node_editing_widgets
node_editing_widgets -->|"accepted edits"| node_interactive_nodes
node_interactive_nodes -->|"crop metadata and result"| node_crop_reinsert
node_collage_node -->|"canvas editing flow"| node_outpaint_widget
node_native_types -->|"image tensors"| node_image_processing
node_font_assets -->|"text rendering fonts"| node_image_processing
node_ingestion -->|"source images"| node_image_processing
node_image_processing -->|"composited images"| node_image_export
node_model_loader -->|"MODEL, CLIP, VAE"| node_native_types
node_civitai -.->|"metadata"| node_model_loader
node_style_assets -->|"style definitions"| node_prompt_styles
node_prompt_styles -->|"conditioning"| node_native_types
node_native_types -->|"images and VAE"| node_latent_prep
node_latent_prep -->|"latents"| node_native_types
node_workflow_widgets -->|"widget state"| node_workflow_nodes
node_settings_widget -->|"backup and restore requests"| node_settings_api
node_example_workflows -.->|"demonstrates"| node_collage_node

click node_registration "https://github.com/raykosan/comfyui_raykostudio/blob/main/__init__.py"
click node_interactive_nodes "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Crop_Image.py"
click node_crop_reinsert "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Insert_Crop.py"
click node_editing_widgets "https://github.com/raykosan/comfyui_raykostudio/blob/main/web/rs_crop.js"
click node_collage_node "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Collage.py"
click node_outpaint_widget "https://github.com/raykosan/comfyui_raykostudio/blob/main/web/rs_outpaint.js"
click node_image_processing "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Adjustments.py"
click node_ingestion "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Load_Images_From_Dir.py"
click node_image_export "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Save_Image.py"
click node_model_loader "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Models_Loader.py"
click node_prompt_styles "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Prompts.py"
click node_latent_prep "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Image_To_Latent.py"
click node_workflow_nodes "https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Any_Switch.py"
click node_workflow_widgets "https://github.com/raykosan/comfyui_raykostudio/blob/main/web/rs_any_switch.js"
click node_settings_api "https://github.com/raykosan/comfyui_raykostudio/blob/main/settings_manager_api.py"
click node_settings_widget "https://github.com/raykosan/comfyui_raykostudio/blob/main/web/settings_manager.js"

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_comfyui,node_registration,node_native_types toneBlue
class node_interactive_nodes,node_crop_reinsert,node_editing_widgets,node_collage_node,node_outpaint_widget toneAmber
class node_model_loader,node_civitai,node_prompt_styles,node_style_assets,node_latent_prep toneMint
class node_image_processing,node_font_assets,node_ingestion,node_image_export toneRose
class node_workflow_nodes,node_workflow_widgets,node_settings_api,node_settings_widget,node_example_workflows toneIndigo
```

## Components

### ComfyUI Host

- **ComfyUI server & canvas**: host runtime · Hosts Python nodes and browser extensions.
- [Extension registration](https://github.com/raykosan/comfyui_raykostudio/blob/main/__init__.py): node loader · Registers RaykoStudio nodes and web extensions. · `__init__.py`
- **ComfyUI native values**: tensor & model types · IMAGE, MASK, LATENT, CONDITIONING, MODEL, CLIP, and VAE values.

### Interactive Editing

- [Queue-gated editing nodes](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Crop_Image.py): Python nodes · Pause execution for crop, spline mask, selection, collage, and outpaint approval. · `Rayko_Crop_Image.py`
- [Crop reinsertion](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Insert_Crop.py): Python node · Reinserts accepted crop results and metadata. · `Rayko_Insert_Crop.py`
- [Editing widgets](https://github.com/raykosan/comfyui_raykostudio/blob/main/web/rs_crop.js): browser modules · Canvas editors synchronize persistent edit state and approval. · `web/rs_crop.js`
- [Collage compositor](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Collage.py): Python node · Canvas-based image composition backend. · `Rayko_Collage.py`
- [Outpaint widget](https://github.com/raykosan/comfyui_raykostudio/blob/main/web/rs_outpaint.js): browser module · Collects canvas outpainting edits. · `web/rs_outpaint.js`

### Generation Inputs

- [Model & LoRA loader](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Models_Loader.py): Python nodes · Loads ComfyUI-managed UNET, CLIP, VAE, and LoRA assets. · `Rayko_Models_Loader.py`
- **Civitai API**: external metadata API · Provides model and LoRA metadata for local caching.
- [Prompts & styles](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Prompts.py): Python nodes · Builds prompts, styles, and conditioning. · `Rayko_Prompts.py`
- **Style data**: repository data
- [Latent preparation](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Image_To_Latent.py): Python nodes · Encodes references or constructs empty latents for downstream samplers. · `Rayko_Image_To_Latent.py`

### Image Output

- [Image processing](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Adjustments.py): Python nodes · Adjustments, alpha/color conversion, text, and comparison operations. · `Rayko_Adjustments.py`
- **Bundled fonts**: rendering assets · Used for server-side high-quality text rendering.
- [Image ingestion](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Load_Images_From_Dir.py): Python nodes · Loads directory batches and source images. · `Rayko_Load_Images_From_Dir.py`
- [Image export](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Save_Image.py): Python nodes · Persists images and paired outputs while preserving workflow context. · `Rayko_Save_Image.py`

### Workflow Control

- [Routing & bypass nodes](https://github.com/raykosan/comfyui_raykostudio/blob/main/Rayko_Any_Switch.py): Python nodes · Provides dynamic routing, bypassing, and iterative sequencing. · `Rayko_Any_Switch.py`
- [Workflow widgets](https://github.com/raykosan/comfyui_raykostudio/blob/main/web/rs_any_switch.js): browser modules · Adds switch, bypass, and loop behavior to the canvas. · `web/rs_any_switch.js`
- [Settings manager API](https://github.com/raykosan/comfyui_raykostudio/blob/main/settings_manager_api.py): server API · Backs up and restores interface settings and can restart the server. · `settings_manager_api.py`
- [Settings manager UI](https://github.com/raykosan/comfyui_raykostudio/blob/main/web/settings_manager.js): browser module · `web/settings_manager.js`
- **Example workflows**: ComfyUI JSON graphs · Distributable collage and outpaint workflow examples.

## Connections

- ComfyUI server & canvas → Extension registration: loads
- Extension registration → Queue-gated editing nodes: registers
- Extension registration → Image processing: registers
- Extension registration → Model & LoRA loader: registers
- Extension registration → Routing & bypass nodes: registers
- Extension registration → Settings manager API: exposes
- ComfyUI server & canvas → Editing widgets: loads frontend extension
- ComfyUI server & canvas → Workflow widgets: loads frontend extension
- ComfyUI server & canvas → Settings manager UI: loads frontend extension
- ComfyUI native values → Queue-gated editing nodes: image and mask inputs
- Queue-gated editing nodes → Editing widgets: preview, edit state, approval
- Editing widgets → Queue-gated editing nodes: accepted edits
- Queue-gated editing nodes → Crop reinsertion: crop metadata and result
- Collage compositor → Outpaint widget: canvas editing flow
- ComfyUI native values → Image processing: image tensors
- Bundled fonts → Image processing: text rendering fonts
- Image ingestion → Image processing: source images
- Image processing → Image export: composited images
- Model & LoRA loader → ComfyUI native values: MODEL, CLIP, VAE
- Civitai API → Model & LoRA loader: metadata
- Style data → Prompts & styles: style definitions
- Prompts & styles → ComfyUI native values: conditioning
- ComfyUI native values → Latent preparation: images and VAE
- Latent preparation → ComfyUI native values: latents
- Workflow widgets → Routing & bypass nodes: widget state
- Settings manager UI → Settings manager API: backup and restore requests
- Example workflows → Collage compositor: demonstrates