# niknah/quick-connections architecture

> Architecture diagram of the GitHub repository niknah/quick-connections, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niknah/quick-connections
- Repository: https://github.com/niknah/quick-connections

## Overview

##### Project Type and Purpose
- This is an open-source plugin/tool for ComfyUI (a Python-based node editor), written in Python (for package registration) and JavaScript (for front-end feature injection). It enhances the graph UI with “quick connections” and “circuit board” style lines. It also offers a standalone demo and optional integration with litegraph.js.

##### File Structure
- Top Level
- .github/workflows/publish.yml → CI/CD for releases
- package.json / pyproject.toml → npm and Python packaging metadata
- __init__.py → Python package entrypoint for ComfyUI manager
- README.md → description and usage
- js/
- QuickConnection.js → main quick-connect logic
- CircuitBoardLines.js → custom line-drawing algorithms
- quick_conn_start.js → bootstrap code to register into ComfyUI front end
- docs/ & example/
- Example HTML/JS and demo pages showing how the plugin is loaded in a browser or via ComfyUI
- imgs/ → screenshots and animations for the README

##### Core Components
a. ComfyUI Host Application (Python back end + front-end UI)
b. ComfyUI Manager (plugin installer)
c. quick-connections Python Package
d. JavaScript Modules
- quick_conn_start.js (initializer)
- QuickConnection.js (UI event hooks)
- CircuitBoardLines.js (rendering engine)
e. Browser Rendering Context (HTML canvas / DOM)
f. Optional litegraph.js Integration
g. Example/Web Server (for demo pages)

##### Relationships & Data Flows
- Plugin Installation
ComfyUI Manager → pip/npm installs quick-connections (Python package + JS assets)
- Initialization at Runtime
ComfyUI Python process loads __init__.py → exposes plugin metadata
Front-end loads quick_conn_start.js → imports QuickConnection.js & CircuitBoardLines.js
- Event Hooking
quick_conn_start → registers “onConnectAttempt” handlers in ComfyUI UI
QuickConnection → intercepts drag events, computes connector endpoints
CircuitBoardLines → generates path coordinates (90°/45° or free angle)
Rendering → UI’s canvas draws custom SVG/Canvas paths instead of default lines
- Example / Demo Mode
Local http.server → serves example HTML → browser loads JS modules directly → shows plugin in isolation
- Optional Path
If litegraph.js is detected → plugin registers adapters to hook into litegraph’s node events

##### Architectural Patterns & Design Principles
- Plugin / Extension Architecture: clear separation between host (ComfyUI) and extension.
- Layered Separation:
- Packaging Layer (Python + npm)
- Initialization Layer (quick_conn_start.js)
- Core Logic Layer (QuickConnection, CircuitBoardLines)
- Integration Layer (ComfyUI hooks, litegraph adapter)
- Configuration / Feature Flags: toggle “Quick connections” and “Circuit Board lines” at runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Packaging Layer
    subgraph "Packaging Layer"
        PyPI["pyproject.toml\n(PyPI Registry)"]:::python
        npmPkg["package.json\n(npm Registry)"]:::javascript
        CI[".github/workflows/publish.yml"]:::external
    end

    %% Installation
    subgraph "Installation"
        Manager["ComfyUI Manager\n(__init__.py)"]:::python
        PyPI -->|"publishes to"| Manager
        npmPkg -->|"publishes to"| Manager
        CI -->|"triggers releases"| PyPI
        CI -->|"triggers releases"| npmPkg
    end

    %% ComfyUI Host
    subgraph "ComfyUI Host Application"
        CoreUI["ComfyUI Core\n(Python Back-end + UI)"]:::python
        Manager -->|"installs plugin"| CoreUI
    end

    %% Initialization Layer
    subgraph "Initialization (Runtime)"
        InitJS["quick_conn_start.js"]:::javascript
        CoreUI -->|"loads initializer"| InitJS
    end

    %% Front-end Modules
    subgraph "Front-end Modules"
        QC["QuickConnection.js"]:::javascript
        CB["CircuitBoardLines.js"]:::javascript
        InitJS -->|"imports"| QC
        InitJS -->|"imports"| CB
    end

    %% Event Handling & Rendering
    subgraph "Runtime Rendering"
        Browser["Browser Rendering Context\n(HTML Canvas / DOM)"]:::external
        QC -->|"computes connector endpoints"| Browser
        CB -->|"generates path coordinates"| Browser
        InitJS -->|"registers hooks"| CoreUI
    end

    %% Optional Integration
    subgraph "Optional litegraph.js Integration"
        Lite["litegraph.js Adapter"]:::external
        InitJS -->|"detects & registers"| Lite
        Lite -->|"hooks node events into"| QC
    end

    %% Demo / Example Mode
    subgraph "Demo / Example"
        HTTP["Local http.server\n(example/run_example.sh)"]:::external
        ExHTML1["example/quick_conn.html"]:::external
        ExJS1["example/quick_conn.js"]:::javascript
        ExHTML2["example/comfyui_quick_conn.html"]:::external
        ExJS2["example/comfyui_quick_conn.js"]:::javascript
        DocsHTML["docs/quick_conn.html"]:::external
        DocsJS["docs/quick_conn.js"]:::javascript

        HTTP --> ExHTML1
        HTTP --> ExHTML2
        HTTP --> DocsHTML
        ExHTML1 --> ExJS1
        ExHTML2 --> ExJS2
        DocsHTML --> DocsJS
    end

    %% Click Events
    click Manager "https://github.com/niknah/quick-connections/blob/main/__init__.py"
    click PyPI "https://github.com/niknah/quick-connections/blob/main/pyproject.toml"
    click npmPkg "https://github.com/niknah/quick-connections/blob/main/package.json"
    click CI "https://github.com/niknah/quick-connections/blob/main/.github/workflows/publish.yml"
    click InitJS "https://github.com/niknah/quick-connections/blob/main/js/quick_conn_start.js"
    click QC "https://github.com/niknah/quick-connections/blob/main/js/QuickConnection.js"
    click CB "https://github.com/niknah/quick-connections/blob/main/js/CircuitBoardLines.js"
    click DocsHTML "https://github.com/niknah/quick-connections/blob/main/docs/quick_conn.html"
    click DocsJS "https://github.com/niknah/quick-connections/blob/main/docs/quick_conn.js"
    click ExHTML1 "https://github.com/niknah/quick-connections/blob/main/example/quick_conn.html"
    click ExJS1 "https://github.com/niknah/quick-connections/blob/main/example/quick_conn.js"
    click ExHTML2 "https://github.com/niknah/quick-connections/blob/main/example/comfyui_quick_conn.html"
    click ExJS2 "https://github.com/niknah/quick-connections/blob/main/example/comfyui_quick_conn.js"
    click HTTP "https://github.com/niknah/quick-connections/blob/main/example/run_example.sh"

    %% Styles
    classDef python fill:#bbdefb,stroke:#1e88e5;
    classDef javascript fill:#c8e6c9,stroke:#43a047;
    classDef external fill:#ffe0b2,stroke:#fb8c00;
```
