From c9b258633a97fbaec629b4292c98c64c48a111a7 Mon Sep 17 00:00:00 2001 From: Mar Date: Sat, 10 Oct 2026 20:55:14 +0000 Subject: [PATCH 1/5] docs(adr): record how the Hub browses models, workflows and apps The repository asks for architectural decisions to be written down, and the Hub's shape was never written. The draft that would have (#17791) argued for one merged grid from a September snapshot, and what shipped is not that: one Hub, one set of furniture, three sections by kind. That difference is the record. The objection to a single grid was that a model and its workflows would read as alternatives; the answer built was to keep them in separate listings rather than to label them once they sit together. Written from the code rather than from the draft, which is how the apps tab's missing toolbar got into it: that section carries only the tabs, and the record says so rather than claiming all three browse alike. The draft's measurements are not carried forward, because they predate what shipped and nobody can reproduce them. --- docs/adr/README.md | 1 + ...ls-workflows-and-apps-browse-as-one-hub.md | 91 +++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md diff --git a/docs/adr/README.md b/docs/adr/README.md index 5ff7ce4fdbb..a73020699dc 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -76,6 +76,7 @@ An Architecture Decision Record captures an important architectural decision mad | [TESTING-BILLING-0031](TESTING-BILLING-0031-real-cloud-checkout-tests.md) | Real Cloud Checkout Tests | Proposed | 2026-09-11 | | [TESTING-E2E-0027](TESTING-E2E-0027-coverage-measurement-and-test-selection.md) | E2E Coverage Measurement and Test Selection | Proposed | 2026-09-01 | | [WEBSITE-ACCEPTANCE-0036](WEBSITE-ACCEPTANCE-0036-separate-live-customer-tests-from-offline-ci.md) | Separate live customer acceptance from offline CI | Proposed | 2026-09-21 | +| [WEBSITE-CATALOGUE-0042](WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md) | Models, Workflows and Apps Browse as One Hub | Accepted | 2026-10-10 | | [WEBSITE-REQUESTS-0030](WEBSITE-REQUESTS-0030-creator-widgets-and-router-request-composition.md) | Creator widgets and Router request composition | Deprecated | 2026-09-09 | | [WIDGET-GROUP-0031](WIDGET-GROUP-0031-dynamic-group-widget-lifecycle.md) | DynamicGroup Widget Lifecycle | Proposed | 2026-09-11 | | [WIDGET-SERIALIZATION-0006](WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md) | PrimitiveNode Widget Restoration Lifecycle | Accepted | 2026-02-22 | diff --git a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md new file mode 100644 index 00000000000..0ed5af8b283 --- /dev/null +++ b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md @@ -0,0 +1,91 @@ +# ADR-WEBSITE-CATALOGUE-0042: Models, Workflows and Apps Browse as One Hub + +Date: 2026-10-10 + +## Status + +Accepted + +## Context + +The site carries three kinds of thing a visitor might want: partner models it +can run in the browser, workflow templates meant to be opened in ComfyUI, and +Comfy Apps. V1 shipped the models catalogue alone, at `/models`. V2 had to +decide whether the other two join the models in one catalogue or browse beside +them as their own. + +A merged catalogue was asked for and prototyped. The risk raised against it was +not that merging is wrong but that the difference between a model and a +workflow has to stay legible to a reader who is not thinking about our data +model, and a single grid blurs it in specific, countable ways: a model and the +workflows that run on it are not peers, workflow titles collide with model +names, a family's operations are configurations rather than competitors, and +one grid would carry two different next steps. + +The earlier draft of this record (#17791, closed) argued the merge from a +snapshot of the catalogue taken in September 2026. Those figures are not +restated here, because they have not been re-measured against what shipped and +a number nobody can reproduce is worse than no number. + +## Decision + +Models, workflows and apps browse as **one Hub with three sections**, not as +one grid and not as separate catalogues. + +- `/hub/models/`, `/hub/workflows/` and `/hub/apps/` are three routes behind + one tab bar. `ModelsCatalogue.vue` owns the tabs and renders exactly one of + `WorkshopModelsGrid`, `WorkflowCatalogue` or `AppCatalogue` per section. +- The sections share their furniture: the same sticky toolbar, the same shelf + and grid layout, and the same card shape and width from `card-layout.ts`. + What differs is the listing, not the way it is browsed. +- Each section lists one kind. A model and the workflows that run on it never + appear in the same list, which is how the central objection to a single grid + is answered: by not putting them side by side at all, rather than by labelling + them once they are. +- Models and workflows carry the full toolbar — search, the use-case filter and + sort — over the same eight use cases, so the filter means the same thing in + both and a reader carries one vocabulary between them. +- Apps carry only the tabs. `AppCatalogue` mounts no search, filter or sort, + because a shelf of a handful of apps is read rather than searched. The tab is + therefore a deliberate exception to "browsed the same way", and the moment + the apps list grows past a screenful it needs revisiting. + +This settles the shape of browsing. It does not settle what belongs on a +workflow page, or where Run lives for a workflow that could run here. + +## Consequences + +### Positive + +- One set of furniture to build, test and restyle. A change to the toolbar, + the shelves or the card lands in all three sections at once, which is what + made the Hub-wide design pass (#20333) a single piece of work. +- The type of a card is implied by the section it is in, so the interface does + not have to disambiguate a workflow titled exactly like a model. +- Each section can answer its own kind honestly: a model card can carry a price + and a Run, a workflow card does not have to pretend to. + +### Negative + +- A visitor who does not know whether what they want is a model, a workflow or + an app has to pick a tab before they can look. Search is per section, so the + thing they want can be one tab away with no sign of it. +- Three listings is three surfaces to keep consistent. They share components, + but nothing structural stops them drifting; consistency is maintained by + convention and by tests, not by the type system. +- The split is by kind rather than by "runs here" against "open in ComfyUI", + which may be the division a visitor actually has in mind. That remains open. + +## Notes + +Open questions this record does not answer: + +1. Where Run lives for a workflow that resolves to a model the site can run. +2. Whether the tabs should split on "runs here" against "open in ComfyUI" + instead of on kind. +3. Whether the interface says _workflows_ or _templates_; the Hub, the repo + data and the copy do not currently agree. + +Written after the fact, from the code as it stands at the Hub design pass +(#20333). It records a decision already built and in production rather than +proposing one. From 50f9966e4e724bb1767c5c1b12f3533ecb02de35 Mon Sep 17 00:00:00 2001 From: Mar Date: Sat, 10 Oct 2026 21:03:46 +0000 Subject: [PATCH 2/5] docs(adr): say what the shared toolbar band actually shares The furniture bullet claimed the sections share a toolbar while the apps bullet said apps mount none, which read as a contradiction. All three do share the sticky band; what differs is what goes in it. --- ...2-models-workflows-and-apps-browse-as-one-hub.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md index 0ed5af8b283..506e3154b0e 100644 --- a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md +++ b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md @@ -35,9 +35,10 @@ one grid and not as separate catalogues. - `/hub/models/`, `/hub/workflows/` and `/hub/apps/` are three routes behind one tab bar. `ModelsCatalogue.vue` owns the tabs and renders exactly one of `WorkshopModelsGrid`, `WorkflowCatalogue` or `AppCatalogue` per section. -- The sections share their furniture: the same sticky toolbar, the same shelf - and grid layout, and the same card shape and width from `card-layout.ts`. - What differs is the listing, not the way it is browsed. +- The sections share their furniture: the same sticky toolbar band, the same + shelf and grid layout, and the same card shape and width from + `card-layout.ts`. What differs is what the band holds and what the list + holds, not the way either is browsed. - Each section lists one kind. A model and the workflows that run on it never appear in the same list, which is how the central objection to a single grid is answered: by not putting them side by side at all, rather than by labelling @@ -46,9 +47,9 @@ one grid and not as separate catalogues. sort — over the same eight use cases, so the filter means the same thing in both and a reader carries one vocabulary between them. - Apps carry only the tabs. `AppCatalogue` mounts no search, filter or sort, - because a shelf of a handful of apps is read rather than searched. The tab is - therefore a deliberate exception to "browsed the same way", and the moment - the apps list grows past a screenful it needs revisiting. + because a shelf of a handful of apps is read rather than searched: the band + is there, with only the tabs in it. The moment the apps list grows past a + screenful this needs revisiting. This settles the shape of browsing. It does not settle what belongs on a workflow page, or where Run lives for a workflow that could run here. From df236d661cfbe164eff97b732f6b0a9b60063e7d Mon Sep 17 00:00:00 2001 From: Mar Date: Sat, 10 Oct 2026 21:10:31 +0000 Subject: [PATCH 3/5] docs(adr): drop the claim that the sections browse identically The furniture bullet still ended by saying the way each section is browsed does not differ, which the apps bullet contradicts. The band and the layout are what is shared; the controls in the band are not. --- ...ALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md index 506e3154b0e..141f4bd8010 100644 --- a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md +++ b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md @@ -37,8 +37,8 @@ one grid and not as separate catalogues. `WorkshopModelsGrid`, `WorkflowCatalogue` or `AppCatalogue` per section. - The sections share their furniture: the same sticky toolbar band, the same shelf and grid layout, and the same card shape and width from - `card-layout.ts`. What differs is what the band holds and what the list - holds, not the way either is browsed. + `card-layout.ts`. What the band holds differs by section, and so does what + the list holds. - Each section lists one kind. A model and the workflows that run on it never appear in the same list, which is how the central objection to a single grid is answered: by not putting them side by side at all, rather than by labelling From 4cd4c04191e62b6714e608dbd8b336fe03519467 Mon Sep 17 00:00:00 2001 From: Mar Date: Sat, 10 Oct 2026 21:21:44 +0000 Subject: [PATCH 4/5] docs(adr): correct what the models and workflows filters share They share the controls, not the vocabulary. Models filter by the eight use cases; workflows filter by their own five categories plus the model a workflow runs on. The record claimed one vocabulary across both, which is not what the two components do, and the divergence is a consequence worth having written down rather than an incidental detail. --- ...models-workflows-and-apps-browse-as-one-hub.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md index 141f4bd8010..b92d47323ef 100644 --- a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md +++ b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md @@ -43,9 +43,12 @@ one grid and not as separate catalogues. appear in the same list, which is how the central objection to a single grid is answered: by not putting them side by side at all, rather than by labelling them once they are. -- Models and workflows carry the full toolbar — search, the use-case filter and - sort — over the same eight use cases, so the filter means the same thing in - both and a reader carries one vocabulary between them. +- Models and workflows both carry search, a filter menu and sort, but they do + not filter over the same thing. Models filter by the eight use cases in + `USE_CASES`; workflows filter by their own five categories in + `workshop-workflow-categories.json`, and additionally by the model a workflow + runs on, which the models section has no counterpart for. The controls match, + the vocabulary does not. - Apps carry only the tabs. `AppCatalogue` mounts no search, filter or sort, because a shelf of a handful of apps is read rather than searched: the band is there, with only the tabs in it. The moment the apps list grows past a @@ -74,6 +77,10 @@ workflow page, or where Run lives for a workflow that could run here. - Three listings is three surfaces to keep consistent. They share components, but nothing structural stops them drifting; consistency is maintained by convention and by tests, not by the type system. +- The two filter menus look alike and mean different things, so a visitor who + learns the use cases in the models tab does not carry them to the workflows + tab. Neither reconciling the two vocabularies nor naming the difference in + the labels has been done. - The split is by kind rather than by "runs here" against "open in ComfyUI", which may be the division a visitor actually has in mind. That remains open. @@ -86,6 +93,8 @@ Open questions this record does not answer: instead of on kind. 3. Whether the interface says _workflows_ or _templates_; the Hub, the repo data and the copy do not currently agree. +4. Whether the models filter and the workflows filter should share one + vocabulary, and which of the two it would be. Written after the fact, from the code as it stands at the Hub design pass (#20333). It records a decision already built and in production rather than From bd1090dd0dfbec819ac76d7f299a15cb5302e275 Mon Sep 17 00:00:00 2001 From: Mar Date: Sat, 10 Oct 2026 21:28:23 +0000 Subject: [PATCH 5/5] docs(adr): the filter labels do name the difference The consequence claimed the labels leave the two filters undistinguished. They do not: the models control reads Use cases, and the workflows control reads Filter with Categories and Model as its groups. What remains is that the vocabularies themselves differ. --- ...0042-models-workflows-and-apps-browse-as-one-hub.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md index b92d47323ef..a2d614ea120 100644 --- a/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md +++ b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md @@ -77,10 +77,12 @@ workflow page, or where Run lives for a workflow that could run here. - Three listings is three surfaces to keep consistent. They share components, but nothing structural stops them drifting; consistency is maintained by convention and by tests, not by the type system. -- The two filter menus look alike and mean different things, so a visitor who - learns the use cases in the models tab does not carry them to the workflows - tab. Neither reconciling the two vocabularies nor naming the difference in - the labels has been done. +- The two filter menus sit in the same place in the band and narrow over + different things. Nothing is mislabelled: the models control reads "Use + cases", and the workflows control reads "Filter" with "Categories" and + "Model" as the groups inside it. But a visitor who learns the eight use cases + in the models tab finds a different five in the workflows tab, and whether + the two should be reconciled is open. - The split is by kind rather than by "runs here" against "open in ComfyUI", which may be the division a visitor actually has in mind. That remains open.