### **Updated Project File Structure**

```text
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.