The publish → run loop (architecture overview)

This is the high-level map of how a published setup gets from authoring in ComfyUI to running on a Comfy server through an external frontend. It is the entry point that ties the detailed setup docs together — read this first for the shape of the loop, then follow the links for storage, schema, and contract detail.

Related docs:

published-setups.md — storage, validation, routes, implementation detail.
published-setup-external-ui-contract.md — the product/design contract behind the external frontend surface.
published-setup-full-circle-plan.md — what is implemented vs. remaining work.
external-frontend-kit.md / setup-runner-quickstart.md — building and exercising a frontend.

The loop, in plain terms

A "setup" is a published, externally-runnable workflow. The loop has two halves that meet at the Koolook server.

flowchart LR
  A["ComfyUI sidebar<br/>author builds &amp; publishes"]
  S["Koolook server<br/>API + setups registry"]
  F["External frontend (WIP)<br/>browse · configure · run"]
  E["ComfyUI engine<br/>runs the graph, writes output"]

  A -->|"publish: POST /koolook/api/setups"| S
  S -->|"browse + load: GET /koolook/api/setups + /{id}"| F
  F -->|"run: POST /koolook/api/setups/{id}/run"| S
  S -->|"queue: POST /prompt"| E
  E -->|"rendered output"| S
  S -->|"status + result: GET /koolook/api/runs/{id}"| F

The publish edge is one-way into the registry; the run / queue / output / status edges form the loop, with the Koolook server mediating both the frontend and the engine.

1. Publish (one-way, into the registry). An author builds a workflow in the Kforge Labs sidebar, drops in Koolook publish-contract nodes, and right-clicks → Publish setup. Koolook captures three things — the visual graph, ComfyUI's executable apiPrompt, and an inferred UI surface (setupSurface.app) — and POSTs the record to the server, which writes it into the setups registry (setups.json). The setup is now a stable, addressable thing with an id.

2. Run (the loop). Any frontend on the same machine talks to the Koolook HTTP API:

Step	Endpoint	What happens
Browse	`GET /koolook/api/setups`	catalog of published setups (valid only)
Load	`GET /koolook/api/setups/{id}`	full record incl. `setupSurface.app` → renders the form
Run	`POST /koolook/api/setups/{id}/run`	user inputs injected into `apiPrompt`, queued on engine
Poll	`GET /koolook/api/runs/{runId}`	status until terminal → returns result path

The Koolook server is the hub: it injects submitted values into the stored prompt, prunes unselected router branches, queues it on the same local ComfyUI server's /prompt, lets the engine run with its installed nodes, and Koolook_PublishOutput writes the files where the user asked. The frontend just renders a form and polls — it never needs to understand the graph.

Why this makes a future frontend possible: the frontend depends only on the published record shape (surface + contract + endpoints), not on ComfyUI internals. Any external UI that speaks those four endpoints can drive renders. The governing rule: don't invent a separate external-app format — the file an external app reads is the same record GET /koolook/api/setups/{id} returns.

Technical map

Three layers — frontend JS → Koolook aiohttp server → ComfyUI engine. Request flow across the loop:

flowchart LR
  P["POST /koolook/api/setups<br/>publish"] --> L["GET /koolook/api/setups<br/>browse"]
  L --> D["GET /koolook/api/setups/{id}<br/>load"]
  D --> R["POST /koolook/api/setups/{id}/run<br/>run"]
  R --> Q["GET /koolook/api/runs/{id}<br/>poll"]

Frontend — browser JS (`web/`)

File	Symbol	Role
`sidebar/modals.js`	`showPublishSetupModal()`	publish dialog; collects metadata + contract
`sidebar/published_surface.js`	`inferSetupSurface()`	infers `setupSurface.app` from publish-contract nodes
`sidebar/canvas_io.js`	`captureWorkflowApiPrompt()`, `serializeFullCanvas()`	exports executable `apiPrompt` + `visualGraph`
`sidebar/published_setups.js`	`publishSavedWorkflowSetup()`	`POST` → `/koolook/api/setups`
`setup_runner_simulator.js`	renders `setupSurface.app`, run + poll	WIP stand-in / contract test for the future frontend

Koolook server — Python · aiohttp (`koolook_routes.py` › `register_routes()`)

Method · path	Handler	Role
`POST /koolook/api/setups`	`publish_setup()`	validate + persist record
`GET /koolook/api/setups`	`list_published_setups()`	catalog (valid only)
`GET /koolook/api/setups/{id}`	`get_published_setup()`	full record incl. `apiPrompt`
`POST /koolook/api/setups/{id}/run`	`run_published_setup()`	inject inputs, prune routers, queue
`GET /koolook/api/runs/{id}`	`get_published_setup_run()`	poll status + result summaries

Behind the routes:

File	Symbol	Role
`koolook_setups.py`	`PublishedSetupRegistry`, `validate_setup()`	schema v1; status `valid` / `draft` / `invalid`
`koolook_setup_runner.py`	`PublishedSetupRunner`, `AiohttpComfyClient`, `InMemorySetupRunStore`	prune branches → `POST /prompt`; run ids `run-000001`
`koolook_setups.py`	`FileSetupStorage`	on-disk registry at `…/koolook-published-setups/setups.json`

ComfyUI engine (same local server)

Method · path	Role
`POST /prompt`	queue prompt; executes graph with installed custom nodes
`GET /history`, `/queue`	status source — runner derives running / done / `lost`

Graph contract nodes: Koolook_PublishInput · Koolook_PublishOutput · Koolook_PublishRouter · Koolook_PublishResult — input injection, output write, branch select, custom result path.

Requirements & contracts

Contract nodes in the setup — Koolook_PublishInput (required), Koolook_PublishOutput (required), Koolook_PublishRouter (optional switch), Koolook_PublishResult (optional result path). Defined in k_publish_contract.py.
Record shape (schemaVersion: 1) — id · metadata · visualGraph · apiPrompt · inputContract · outputContract · setupSurface.app · source · validation.
Validation — validation.status ∈ {valid, draft, invalid}; a valid record must carry an apiPrompt.
Run contract — body { "inputs": { … } } → { runId, promptId, status }; poll returns terminal status + result paths.
One format only — the file an external app reads === the record GET /koolook/api/setups/{id} returns. Do not create an external-app-only format.

Implementation notes worth knowing

Routes register independently of nodes. koolook_routes.install() runs even when a node module fails to import, so the setup/preset API stays up when a node is broken.
Run ids are in-memory (InMemorySetupRunStore, run-000001…). They do not survive a ComfyUI restart; a poll for a missing run returns a terminal lost status. Persisted run history is listed as remaining work in the full-circle plan.
The simulator is the contract test. setup_runner_simulator.html/.js renders from setupSurface.app exactly as the real frontend must, so it doubles as the build-against reference. It is a maintainer harness, not the production frontend.

Status

The core loop (publish → registry → load → run → poll → result) is implemented (PRs 231 / 233 / 235). Remaining "future" work: the production external frontend itself (auth, job list, run history, multi-user) and the publish-modal simplification — see published-setup-full-circle-plan.md.