# komikndr/raylight architecture

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

- Interactive diagram: https://gitdiagram.com/komikndr/raylight
- Repository: https://github.com/komikndr/raylight

## Overview

Raylight is a ComfyUI extension for multi-GPU diffusion sampling: workflow nodes configure parallelism and launch Ray workers, which run distributed sampling and return results. The main stages are node registration and orchestration, worker/topology setup, model loading and patching, distributed diffusion/attention, and output decoding. README-documented capabilities include USP, CFG, FSDP, LoRA, quantized loading, ControlNet, and distributed VAE decoding. Several relationships below are evidenced by the source index or README; unsampled implementation details are not inferred.

Main entry points: [`src/raylight/distributed_worker/ray_worker.py`](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/ray_worker.py) (Ray worker), [`src/raylight/nodes.py`](https://github.com/komikndr/raylight/blob/main/src/raylight/nodes.py) (Workflow nodes), [`src/raylight/comfy_dist/sd.py`](https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/sd.py) (Distributed model loading), [`src/raylight/distributed_modules/usp.py`](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_modules/usp.py) (Unified sequence parallelism)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["ComfyUI workflow"]
  node_extension["Extension registration<br/>[__init__.py]"]
  node_workflow["Workflow nodes<br/>[nodes.py]"]
  node_sampler["Custom sampler"]
end

subgraph group_orchestration["Ray orchestration"]
  node_worker["Ray worker<br/>[ray_worker.py]"]
  node_worker_config["Worker configuration"]
  node_groups["Parallel group setup"]
end

subgraph group_model["Model preparation"]
  node_model_load["Distributed model loading<br/>[sd.py]"]
  node_model_patch["Model patching<br/>[model_patcher.py]"]
  node_lora["LoRA support<br/>[lora.py]"]
  node_quant["Quantized model support<br/>[quant_ops.py]"]
  node_gguf["GGUF integration<br/>[nodes.py]"]
end

subgraph group_parallel["Distributed sampling"]
  node_usp["Unified sequence parallelism<br/>[usp.py]"]
  node_cfg["CFG parallelism<br/>[cfg.py]"]
  node_attention["Distributed attention<br/>[attention.py]"]
  node_wan["Wan sequence implementation"]
  node_omnigen["OmniGen sequence implementation"]
  node_controlnet["Distributed ControlNet"]
end

subgraph group_outputs["Decode and progress"]
  node_vae["Distributed VAE decode<br/>[ray_worker_vae.py]"]
  node_decode_progress["Decode progress<br/>[decode_progress.py]"]
  node_progress["Sampler progress<br/>[progress.py]"]
end

node_comfy(("ComfyUI"))

node_comfy -.->|"loads extension"| node_extension
node_extension -->|"imports mappings"| node_workflow
node_comfy -.->|"runs nodes"| node_workflow
node_workflow -->|"launches workers"| node_worker
node_workflow -->|"configures workers"| node_worker_config
node_workflow -->|"uses progress"| node_progress
node_workflow -->|"uses decode status"| node_decode_progress
node_sampler -->|"patches sampler"| node_workflow
node_worker -->|"reads config"| node_worker_config
node_worker -->|"initializes topology"| node_groups
node_groups -->|"derives parallel config"| node_worker_config
node_worker -->|"patches USP"| node_usp
node_worker -->|"patches CFG"| node_cfg
node_worker -->|"dispatches control"| node_controlnet
node_worker -->|"dispatches decode"| node_vae
node_worker -->|"reports progress"| node_progress
node_vae -->|"updates status"| node_decode_progress
node_usp -->|"uses model handler"| node_wan
node_usp -->|"uses model handler"| node_omnigen
node_wan -->|"uses attention"| node_attention
node_omnigen -->|"uses attention"| node_attention
node_workflow -->|"loads model"| node_model_load
node_model_load -.->|"uses patcher"| node_model_patch
node_workflow -.->|"loads LoRA"| node_lora
node_worker -->|"uses quant operations"| node_quant
node_model_load -->|"supports GGUF loading"| node_gguf

click node_extension "https://github.com/komikndr/raylight/blob/main/__init__.py"
click node_workflow "https://github.com/komikndr/raylight/blob/main/src/raylight/nodes.py"
click node_sampler "https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_extra_dist/nodes_custom_sampler.py"
click node_worker "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/ray_worker.py"
click node_worker_config "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/raylightworker_config_schema.py"
click node_groups "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/parallel_group_manager.py"
click node_model_load "https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/sd.py"
click node_model_patch "https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/model_patcher.py"
click node_lora "https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/lora.py"
click node_quant "https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/quant_ops.py"
click node_usp "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_modules/usp.py"
click node_cfg "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_modules/cfg.py"
click node_attention "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_modules/attention.py"
click node_wan "https://github.com/komikndr/raylight/blob/main/src/raylight/diffusion_models/wan/xdit_context_parallel.py"
click node_omnigen "https://github.com/komikndr/raylight/blob/main/src/raylight/diffusion_models/omnigen/xdit_context_parallel.py"
click node_controlnet "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/ray_worker_controlnet.py"
click node_vae "https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/ray_worker_vae.py"
click node_decode_progress "https://github.com/komikndr/raylight/blob/main/src/raylight/decode_progress.py"
click node_progress "https://github.com/komikndr/raylight/blob/main/src/raylight/progress.py"
click node_gguf "https://github.com/komikndr/raylight/blob/main/src/raylight/expansion/comfyui_gguf/nodes.py"

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_extension,node_workflow,node_sampler,node_comfy toneBlue
class node_worker,node_worker_config,node_groups toneAmber
class node_model_load,node_model_patch,node_lora,node_quant,node_gguf toneMint
class node_usp,node_cfg,node_attention,node_wan,node_omnigen,node_controlnet toneRose
class node_vae,node_decode_progress,node_progress toneIndigo
```

## Components

### ComfyUI workflow

- [Extension registration](https://github.com/komikndr/raylight/blob/main/__init__.py): `__init__.py`
- [Workflow nodes](https://github.com/komikndr/raylight/blob/main/src/raylight/nodes.py): `src/raylight/nodes.py`
- [Custom sampler](https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_extra_dist/nodes_custom_sampler.py): `src/raylight/comfy_extra_dist/nodes_custom_sampler.py`

### Ray orchestration

- [Ray worker](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/ray_worker.py): `src/raylight/distributed_worker/ray_worker.py`
- [Worker configuration](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/raylightworker_config_schema.py): `src/raylight/distributed_worker/raylightworker_config_schema.py`
- [Parallel group setup](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/parallel_group_manager.py): `src/raylight/distributed_worker/parallel_group_manager.py`

### Model preparation

- [Distributed model loading](https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/sd.py): `src/raylight/comfy_dist/sd.py`
- [Model patching](https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/model_patcher.py): `src/raylight/comfy_dist/model_patcher.py`
- [LoRA support](https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/lora.py): `src/raylight/comfy_dist/lora.py`
- [Quantized model support](https://github.com/komikndr/raylight/blob/main/src/raylight/comfy_dist/quant_ops.py): `src/raylight/comfy_dist/quant_ops.py`
- [GGUF integration](https://github.com/komikndr/raylight/blob/main/src/raylight/expansion/comfyui_gguf/nodes.py): `src/raylight/expansion/comfyui_gguf/nodes.py`

### Distributed sampling

- [Unified sequence parallelism](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_modules/usp.py): `src/raylight/distributed_modules/usp.py`
- [CFG parallelism](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_modules/cfg.py): `src/raylight/distributed_modules/cfg.py`
- [Distributed attention](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_modules/attention.py): `src/raylight/distributed_modules/attention.py`
- [Wan sequence implementation](https://github.com/komikndr/raylight/blob/main/src/raylight/diffusion_models/wan/xdit_context_parallel.py): `src/raylight/diffusion_models/wan/xdit_context_parallel.py`
- [OmniGen sequence implementation](https://github.com/komikndr/raylight/blob/main/src/raylight/diffusion_models/omnigen/xdit_context_parallel.py): `src/raylight/diffusion_models/omnigen/xdit_context_parallel.py`
- [Distributed ControlNet](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/ray_worker_controlnet.py): `src/raylight/distributed_worker/ray_worker_controlnet.py`

### Decode and progress

- [Distributed VAE decode](https://github.com/komikndr/raylight/blob/main/src/raylight/distributed_worker/ray_worker_vae.py): `src/raylight/distributed_worker/ray_worker_vae.py`
- [Decode progress](https://github.com/komikndr/raylight/blob/main/src/raylight/decode_progress.py): `src/raylight/decode_progress.py`
- [Sampler progress](https://github.com/komikndr/raylight/blob/main/src/raylight/progress.py): `src/raylight/progress.py`

### Other components

- **ComfyUI**

## Connections

- ComfyUI → Extension registration: loads extension
- Extension registration → Workflow nodes: imports mappings (evidence: `__init__.py`)
- ComfyUI → Workflow nodes: runs nodes
- Workflow nodes → Ray worker: launches workers (evidence: `src/raylight/nodes.py`)
- Workflow nodes → Worker configuration: configures workers (evidence: `src/raylight/nodes.py`)
- Workflow nodes → Sampler progress: uses progress (evidence: `src/raylight/nodes.py`)
- Workflow nodes → Decode progress: uses decode status (evidence: `src/raylight/nodes.py`)
- Custom sampler → Workflow nodes: patches sampler (evidence: `src/raylight/comfy_extra_dist/nodes_custom_sampler.py`)
- Ray worker → Worker configuration: reads config (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Ray worker → Parallel group setup: initializes topology (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Parallel group setup → Worker configuration: derives parallel config (evidence: `src/raylight/distributed_worker/parallel_group_manager.py`)
- Ray worker → Unified sequence parallelism: patches USP (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Ray worker → CFG parallelism: patches CFG (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Ray worker → Distributed ControlNet: dispatches control (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Ray worker → Distributed VAE decode: dispatches decode (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Ray worker → Sampler progress: reports progress (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Distributed VAE decode → Decode progress: updates status (evidence: `src/raylight/distributed_worker/ray_worker_vae.py`)
- Unified sequence parallelism → Wan sequence implementation: uses model handler (evidence: `src/raylight/distributed_modules/usp.py`)
- Unified sequence parallelism → OmniGen sequence implementation: uses model handler (evidence: `src/raylight/distributed_modules/usp.py`)
- Wan sequence implementation → Distributed attention: uses attention (evidence: `src/raylight/diffusion_models/wan/xdit_context_parallel.py`)
- OmniGen sequence implementation → Distributed attention: uses attention (evidence: `src/raylight/diffusion_models/omnigen/xdit_context_parallel.py`)
- Workflow nodes → Distributed model loading: loads model (evidence: `src/raylight/nodes.py`)
- Distributed model loading → Model patching: uses patcher (evidence: `src/raylight/comfy_dist/sd.py`)
- Workflow nodes → LoRA support: loads LoRA
- Ray worker → Quantized model support: uses quant operations (evidence: `src/raylight/distributed_worker/ray_worker.py`)
- Distributed model loading → GGUF integration: supports GGUF loading (evidence: `src/raylight/comfy_dist/sd.py`)
