app/

Application-level managers that sit between the HTTP server and the rest of the runtime. Compared with the diffusion engine, these are small focused pieces — none of them are larger than a few hundred lines except the user manager and the assets system.

Layout

app/
├── __init__.py
├── logger.py                   # logging setup, get_logs / startup warning helpers
├── app_settings.py             # User-facing settings
├── frontend_management.py      # Resolves --front-end-version, serves web/
├── custom_node_manager.py      # /custom_nodes routes for the UI
├── model_manager.py            # /models endpoints, model file resolution
├── node_replace_manager.py     # Node replacement registry (V3 NodeReplace)
├── subgraph_manager.py         # Subgraph (collapsible group) tracking
├── user_manager.py             # User accounts + per-user data dirs
├── database/                   # Core DB models + migration entry
│   ├── db.py                   # init_db, file lock, alembic upgrade
│   └── models.py               # Base, naming convention
└── assets/                     # The asset system (the big one)
    ├── api/                    # /assets HTTP routes
    ├── database/               # Asset DB models (assets, references, tags, meta)
    ├── services/               # Hashing, ingest, tagging, metadata extraction
    ├── helpers.py              # get_utc_now, etc.
    ├── scanner.py              # Background filesystem scanner
    └── seeder.py               # Seeder lifecycle (start, pause, shutdown)

Key components

app/logger.py

Configures Python logging once. setup_logger(log_level, use_stdout) is called from main.py. get_logs() returns the in-memory log buffer that the /internal/logs route serves. log_startup_warning(...) and print_startup_warnings() accumulate non-fatal startup issues so they appear after server initialization.

app/frontend_management.py

FrontendManager.parse_version parses strings like Comfy-Org/ComfyUI_frontend@latest or Comfy-Org/ComfyUI_frontend@1.2.2. The manager:

• Resolves latest against the GitHub releases API.
• Downloads and caches the bundle to a local cache directory.
• Falls back to the pip-installed comfyui-frontend-package when offline or when no --front-end-version flag is set.
• Serves the chosen bundle from the path returned by FrontendManager.get_required_frontend_version and friends.

app/custom_node_manager.py

Handles the /custom_nodes HTTP routes. nodes.init_extra_nodes is the loader; this file is the UI/API surface the frontend uses for listing installed custom nodes. Plays nicely with ComfyUI-Manager when --enable-manager is on.

app/model_manager.py

Powers /models/<folder_name> endpoints. Resolves model file existence and previews; the underlying directory registry is folder_paths.folder_names_and_paths.

app/user_manager.py

Implements the --multi-user mode: per-user directories under user/, JSON-based settings, and per-user file scoping. ~19 KB. Without --multi-user, all data goes to a single user/default/ directory.

app/subgraph_manager.py / app/node_replace_manager.py

Subgraphs are reusable groups of nodes that the frontend can collapse. The backend doesn't render them, but it tracks them so prompts that reference them can be expanded correctly.

NodeReplaceManager is the runtime-registered "replace this node class with that one" map exposed via comfy_api.latest.NodeReplacement.register. Used to deprecate or remap nodes without breaking saved workflows.

app/database/

Bootstraps SQLite via Alembic. init_db() in db.py:

1. Reads --database-url (default sqlite:///<repo>/user/comfyui.db).
2. For in-memory URLs, creates schema directly via Base.metadata.create_all.
3. For file URLs, runs alembic upgrade head, backing up the file beforehand and restoring on failure.
4. Acquires an OS-level file lock on <db>.lock (cross-platform via filelock).

Migrations live in alembic_db/versions/ — see Tooling.

The Base declarative class is in app/database/models.py with naming conventions pinned via NAMING_CONVENTION so Alembic-generated migrations have predictable index/constraint names.

app/assets/

The largest sub-area — see Asset system for the full picture. The shape:

• Database models (app/assets/database/models.py): Asset, AssetReference, AssetReferenceMeta, AssetReferenceTag, Tag. Assets are content-addressed by hash; references are paths/names with mtime tracking.
• Services (app/assets/services/): hashing.py (BLAKE3/SHA), ingest.py (register a file), bulk_ingest.py (bulk imports), metadata_extract.py (image/video metadata), tagging.py, path_utils.py.
• Background workers (app/assets/scanner.py, app/assets/seeder.py): walk models/, input/, output/ and populate the DB asynchronously when --enable-assets is set.
• HTTP API (app/assets/api/routes.py, schemas_in.py, schemas_out.py, upload.py): the /assets/... REST surface.

Integration points

• app/logger.py is imported by main.py before anything else logs.
• app/frontend_management.py, app/user_manager.py, app/model_manager.py, app/custom_node_manager.py, app/subgraph_manager.py, app/node_replace_manager.py are constructed in server.PromptServer.__init__.
• app/database/db.py:init_db is called from setup_database in main.py.
• app/assets/seeder.py:asset_seeder is started conditionally in setup_database.

Where to start a change

• Add a new HTTP endpoint that's frontend-only: see api_server/routes/internal/internal_routes.py and the per-manager routes (e.g., app/custom_node_manager.py's routes are added in server.py).
• Add a new asset metadata field: extend AssetReferenceMeta (key/value pattern, no schema change needed) or add a column to AssetReference and write an Alembic migration.
• New per-user setting: add to app/app_settings.py and surface in user_manager.py.