JasonHoku-ComfyUI-Ultimate-Auto-Sampler-Config-Grid-Testing-Suite/ProjectStructure.md

Updated Project File Structure

ComfyUI-Ultimate-Sampler-Grid/
├── __init__.py                  # Server Routes & Node Mappings
├── sampler_node.py              # Main "Sampler Grid" Node
├── dashboard_node.py            # "Dashboard Viewer" Node
├── config_builder_node.py       # "Config Builder" Node
├── json_text_node.py            # "Smart JSON" Node
│
├── generation_orchestrator.py   # The "Conductor" (Loop Logic)
├── image_generation.py          # KSampler & VAE Wrappers
├── model_loader.py              # Checkpoint/LoRA Loading Logic
├── model_cache.py               # 3-Tier Model Caching System
├── remote_vae.py                # Remote VAE Offloading
│
├── lora_utils.py                # LoRA Searching & Validation
├── trigger_words.py             # CivitAI Trigger Word Fetching
├── html_generator.py            # Reads /resources/ to build the Dashboard HTML
│
├── web/                         # [ComfyUI Integration Layer]
│   ├── dashboard.js             # Registers Dashboard Node & Message Handling
│   ├── config_builder.js        # Registers Builder Node & Custom UI Widget
│   └── smart_json_text.js       # Registers JSON Node & Syntax Highlighting
│
└── resources/                   # [The Dashboard SPA Core]
    ├── template.html            # HTML Skeleton for the generated report
    ├── report.css               # Styling (Infinite Canvas, Cards, Modals)
    ├── logic_init.js            # Bootstrapper (Load JSON, Init State)
    ├── logic_state.js           # State Store (Redux-style: filters, favorites)
    ├── logic_pipeline.js        # Data Processing (Filter -> Sort -> Layout)
    ├── logic_virtual.js         # Virtual DOM / Infinite Scroller Engine
    ├── logic_ui.js              # UI Renderer (DOM creation, Modal handling)
    ├── logic_events.js          # Interaction Handler (Hotkeys, API calls)
    └── logic_utils.js           # Helpers (Debounce, Formatters)

---

Project Architecture Overview

ComfyUI-Ultimate-Sampler-Grid is a hybrid application.

1. The Backend (Python): Runs inside ComfyUI. It orchestrates the grid generation, manages resources (caching/loading), and serves the API.
2. The Frontend Bridge (JS): Runs in the ComfyUI browser tab. It registers the custom nodes and widgets.
3. The Dashboard SPA (HTML/JS/CSS): A standalone, virtualized "IDE" for viewing results. It is generated by the backend but runs entirely in the client's browser, communicating back to the server only when saving changes.

---

1. The Backend: Core Logic & Orchestration

Located in the root directory.

• sampler_node.py (The Interface)

• Role: The primary ComfyUI node. Validates inputs and passes control to the orchestrator.

• Key Logic: Disables caching features if "Optional" inputs are connected (since external changes can't be tracked).

• generation_orchestrator.py (The Conductor)

• Role: Manages the generation loop.

• Key Logic:

• Smart Skip: Checks manifest.json to skip existing images.

• Lookahead: Triggers background loading for the next job while the current one runs.

• Interrupts: Catches cancel signals to save the manifest before stopping.

• image_generation.py (The Worker)

• Role: Wraps KSampler and VAE Decode.

• Key Logic: Implements flush_batch_with_vae to save images and update the manifest in chunks (preventing VRAM overflow).

• html_generator.py (The Builder)

• Role: Compiles the SPA.

• Key Logic: Reads all files from /resources/, injects them into template.html, and embeds the manifest.json data as a JavaScript variable (fullManifest), allowing the dashboard to load instantly without an initial API call.

---

2. The Backend: Resource Management

Located in the root directory.

• model_cache.py (The 3-Tier Cache)

• Role: Thread-safe resource manager.

• Tiers: 1. Raw Files (RAM), 2. Incremental States (Partial LoRA stacks), 3. Final Results (Patched Models).

• conditioning_cache.py (The Prompt Cache)

• Role: Caches CLIP text encodings to disk.

• Key Logic: Hashes (Prompt + CLIP State + LoRA Config) to ensure validity.

• batch_encoding.py (The Accelerator)

• Role: Bulk prompt encoder.

• Key Logic: Scans the grid for all prompts using the current model and encodes them in one massive GPU batch.

---

3. The Frontend: ComfyUI Integration

Located in /web/.

• dashboard.js

• Role: Registers the Dashboard node. Listens for server events to update the iframe.

• config_builder.js

• Role: Registers the Builder node. Provides the complex UI for creating JSON configs.

• smart_json_text.js

• Role: Registers the JSON node. Adds syntax highlighting and validation.

---

4. The Frontend: The Dashboard SPA

Located in /resources/. This is the "App" users interact with.

• logic_init.js (The Bootstrapper)

• Role: Main Entry Point.

• Key Logic:

• initDashboard(): The first function called.

• Data Injection: detects if fullManifest exists (injected by Python). If not, it attempts to fetch it (View Mode).

• Lifecycle: Calls initLogicState() -> applyPipeline() -> initVirtualScroller() -> initGlobalEvents().

• logic_state.js (The Brain)

• Role: Central State Store (Redux-style).

• Key Logic:

• State Object: Holds items (all images), filteredItems (visible), selection (active card), and favorites.

• Triple JSON Lists: Manages the logic for the "Accepted", "Favorites", and "Rejected" JSON bars at the bottom of the UI.

• Persistence: Saves user preferences (Sort Order, Column Count) to localStorage so they persist across reloads.

• logic_events.js (The Handler)

• Role: Interaction & API Bridge.

• Key Logic:

• Keyboard Shortcuts: Maps Arrow Keys (Pan), Space (Scroll), +/- (Zoom), F (Fit).

• API Calls: Uses fetch to hit endpoints like /config_tester/save_manifest (when you star/reject an image) and /config_tester/delete_session.

• Live Updates: Listens for the executed event from ComfyUI to trigger a soft-refresh of the image list.

• logic_virtual.js (The Engine)

• Role: Virtual Scroller.

• Key Logic: Calculates viewport geometry to render only the ~20 visible cards out of thousands, enabling high performance.

• logic_pipeline.js (The Processor)

• Role: Filtering & Sorting.

• Key Logic: Transforms the raw item list based on active filters (Model, Sampler, etc.) before passing it to the virtual scroller.

• logic_ui.js (The Renderer)

• Role: DOM Manipulation.

• Key Logic: Generates the HTML for individual cards and the "Revise" modal.

• logic_utils.js (The Helpers)

• Role: Utilities.

• Key Logic: Debouncers, formatters, and helper functions.

---

Summary of Data Flow

1. User Config: You set parameters in the Sampler Node (Python).
2. Expansion: generation_orchestrator.py expands this into a list of jobs.
3. Generation: The backend loops through jobs, using ModelCache and ConditioningCache for speed.
4. Storage: Images are saved to disk; metadata is appended to manifest.json.
5. Compilation: html_generator.py reads the manifest.json and all .js files in /resources/, baking them into a single dashboard_html string.
6. Display: The Dashboard Node (JS) renders this HTML in an iframe.
7. Boot: logic_init.js wakes up, loads the data into logic_state.js, and logic_virtual.js starts rendering cards.
8. Interaction: You click "Favorite" in the UI -> logic_events.js sends an API request to __init__.py -> Python updates manifest.json on disk.