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..a2d614ea120 --- /dev/null +++ b/docs/adr/WEBSITE-CATALOGUE-0042-models-workflows-and-apps-browse-as-one-hub.md @@ -0,0 +1,103 @@ +# 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 band, the same + shelf and grid layout, and the same card shape and width from + `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 + them once they are. +- 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 + 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. + +## 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 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. + +## 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. +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 +proposing one.