komlevv-komlevv-Align-ComfyUI/docs/PROJECT_ARCHITECTURE.md

Project architecture

• Status: stable
• Scope: stable repository architecture, subsystem boundaries, extension points, and document ownership
• Applies to: entire repository, especially web/js/** and docs/**
• Source of truth level: architecture
• Last verified commit: 9bb835c68f9a68ecccdbeae32bd41382a1eb3556
• Update when: directory structure, subsystem boundaries, integration strategy, or document ownership changes
• Supersedes: none
• Superseded by: none

Purpose

This document describes the stable architecture of the repository and the intended ownership boundaries of its current frontend subsystem.

It is not a task log and not a changelog.

Repository shape

Current high-level layout:

• __init__.py — ComfyUI custom node package entrypoint and WEB_DIRECTORY export
• pyproject.toml — package metadata
• web/js/align_panel.js — main frontend extension module
• web/js/align_actions.js — toolbar action registry and SVG icons
• web/js/align_panel.css — toolbar-specific CSS loaded from JS
• docs/ — multi-file agent context system
• README.md and preview.png — human-facing overview and preview asset

Frontend architecture principles

1. Work inside the current flat web/js layout

This repository currently uses a flat frontend file layout under web/js. Do not introduce a new nested feature subfolder unless there is a strong repository-level reason and the architecture docs are updated in the same change.

2. Keep one feature, one frontend module cluster

The active frontend subsystem is the align toolbar. Keep these responsibilities distinct but adjacent:

• toolbar mounting and action dispatch in align_panel.js
• action metadata and icon definitions in align_actions.js
• style rules in align_panel.css

Do not merge SVG data into unrelated docs or Python files.

3. CSS must be loaded from JS

web/js files auto-load as JavaScript modules. Non-JS assets do not. If CSS is required, load it from JS.

4. Prefer simple browser-native UI where sufficient

The current toolbar intentionally uses:

• a persistent action bar integration instead of a toggleable panel
• native browser title tooltips instead of custom tooltip DOM

Do not reintroduce custom tooltip infrastructure or disabled-state UI unless the task explicitly requires it.

Subsystem boundaries

Align Toolbar

Owns:

• injecting the toolbar into the built-in ComfyUI action bar
• the six alignment actions
• selection handling for nodes, groups, and reroute dots
• minimal CSS for toolbar sizing and icon rendering
• native tooltip text through the button title attribute

Does not own:

• custom color workflows
• canvas/background rendering
• link/reroute visual style beyond participation in alignment selection
• keyboard shortcut panels or command palettes

Extension strategy

Prefer official extension points

When there is a documented frontend extension point or stable hook, prefer it.

Patch internals only when required

The current implementation depends on a narrow DOM integration with the built-in ComfyUI action bar and on LiteGraph selection/runtime objects. When touching those internals:

• keep the patch scope as narrow as possible
• document the touchpoint and reason in the relevant feature doc
• re-check upstream files when versions change

Document ownership

• repository-wide behavior rules live in AGENTS.md
• architecture boundaries live here
• compatibility assumptions live in docs/COMPATIBILITY.md
• subsystem truth lives in docs/features/*.md
• operational tool workflows live in docs/tools/*.md
• current problem state lives in docs/tasks/*.md
• historical session or branch continuation context lives in docs/handoffs/*.md
• durable rationale lives in docs/DECISIONS/*.md

Maintenance rule

Any non-trivial architecture or ownership change must update this file in the same commit.