0nikod-ComfyUI-Simple-Prompt/README_ARCH.md

ComfyUI-Simple-Prompt Architecture Documentation

This document describes the architectural design of ComfyUI-Simple-Prompt after the v0.1.0 refactor. The main goal of this refactor was to decouple the core business logic from the ComfyUI framework and support hot reloading during development.

Directory Structure

ComfyUI-Simple-Prompt/
├── simple_prompt/
│   ├── __init__.py           # Package initialization
│   ├── core/                 # Core business logic (platform-independent)
│   │   ├── config.py         # Path configurations
│   │   ├── database.py       # DuckDB connection and initialization
│   │   ├── tags.py           # Tag search and management logic
│   │   ├── categories.py     # Category management logic
│   │   ├── presets.py        # Preset management logic
│   │   └── utils.py          # General utility functions
│   ├── api/                  # API abstraction layer
│   │   └── handlers.py       # Pure functional request handlers
│   └── comfyui/              # ComfyUI adapter layer
│       ├── nodes.py          # Node definitions (SimplePrompt)
│       └── server.py         # PromptServer route registration & hot reload logic
├── tests/                    # Unit tests
├── js/                       # Frontend build artifacts
├── src/                      # Frontend source code
├── __init__.py               # ComfyUI entry point
└── pyproject.toml            # Python project configuration

Core Design

1. Layered Architecture

• Core Layer (simple_prompt/core): Contains pure Python logic, independent of aiohttp or ComfyUI. All data operations (DuckDB, JSON read/write) are handled in this layer.
• API Layer (simple_prompt/api): handlers.py acts as an intermediate layer, receiving parameters, calling Core layer functions, and returning standard Python dictionaries/lists.
• Adapter Layer (simple_prompt/comfyui): Responsible for forwarding PromptServer requests to the API layer and wrapping the results in web.json_response.

2. Data Management

• Uses DuckDB as the primary query engine, merging multiple Parquet data sources (Main repository, User custom, Liked, Default) through Views.
• Configuration files (categories, presets) are stored as JSON.
• All data paths are centrally managed in simple_prompt/core/config.py.

Development Guide

Hot Reload

To improve development efficiency, the backend supports modifying code without restarting ComfyUI.

How to enable: Set the environment variable SIMPLE_PROMPT_DEV=1 when starting ComfyUI.

Windows (PowerShell):

$env:SIMPLE_PROMPT_DEV="1"
.\run_nvidia_gpu.bat  # Or your startup script

How it works:

• simple_prompt/comfyui/server.py contains a _maybe_reload() function.
• Every API request (e.g., tag search) triggers this function. If in development mode, it uses importlib.reload to reload all modules under simple_prompt.core and simple_prompt.api.
• Note: After modifying nodes.py (node definitions) or server.py (route registration), you still need to restart ComfyUI as these are registered at startup.

Running Tests

Use pytest to run unit tests:

uv run pytest tests/ -v

The test environment is independent and does not rely on the ComfyUI runtime.