Domain model

Luigi’s Box AI separates catalog data from the discovery experiences that use it. The concepts below connect your account, indexed data, backend configuration, and storefront components.

How they fit together

An organization owns one or more catalogs. Each catalog contains discoverable data, while channels, surfaces, and widgets control how that data is exposed to shoppers.

Concept	What it is
Organization	Your company, the account that owns everything below it.
Catalog	One set of products and other discoverable objects in a single language, with its own settings. Use separate catalogs for different languages or regions.
Channel	A view over a catalog for a market or storefront. It controls which objects are visible and which attribute values shoppers see, so one catalog can support different markets.
Surface	A configured discovery experience. See Surfaces and widgets.
Collection	A listing a collection surface can serve: each category as a listing of its products, one named filter, or every object of one type. The first two are registered on a catalog. See Collections.
Widget	A storefront component that renders a surface. See Surfaces and widgets.
Visitor	An anonymous shopper interacting with a surface, identified only within your privacy and consent settings.

Surfaces and widgets

A surface is the configured backend discovery experience that your storefront calls through the API. A widget is the frontend component that calls a compatible surface and renders its response.

Luma is Luigi’s Box AI’s browser framework for widgets: autocomplete, search results, category listings and recommenders, rendered into your storefront from a distribution repository.

A surface has one intent — the kind of discovery it performs, decided by what the request gives it to work with. There are three:

Intent	The request supplies	Endpoint	Typical placements
search	A search query	POST /discovery/v1/search	Search-as-you-type panel, search results page
recommender	Anchor objects (or nothing)	POST /discovery/v1/recommender	Product detail page, cart, homepage, email
collection	A collection, such as a category	POST /discovery/v1/collection	Category and brand listing pages, landing pages

The intent is visible in the surface’s ID (lbs_search_main), and it must match the endpoint you call. Sending a recommender surface to /search is rejected.

Autocomplete is not its own intent. The as-you-type panel consumes a search query, so it is served by a search surface — usually the same one as the results page.

A surface is called from every page that shows the same recommendations; the request’s touchpoint tells the calls apart. Several surfaces share an intent when they behave differently: similar items and bought-together are separate recommender surfaces, tuned independently, and a place that needs its own tuning or business rules has a surface of its own.

Each surface also declares which catalog object types it works with:

Field	What it declares
output_types	The object types the surface may answer with. A surface that returns products and categories declares both.
input_type	The object type of the anchors a recommender surface is queried with, such as the product a related-items widget is anchored on. Recommender surfaces only — the other intents take no anchor.

Both are properties of the surface rather than of its intent, and you can change them on an existing surface without recreating it.

Touchpoints

Where the intent says what a surface does, the touchpoint says where the answer appears. Every discovery request should declare one in its touchpoint parameter: it is what lets your analytics tell apart results served at different points of the shopping journey. A request without one is served, and its results are recorded with no touchpoint.

Touchpoint	Where the shopper sees the results	Intents it serves
autocomplete	The as-you-type panel, before the query is submitted	search, recommender
serp	The search results page	search, recommender
plp	A category or brand listing	collection, recommender
landing_page	A curated or campaign collection page	collection, recommender
homepage	Homepage modules	collection, recommender
pdp	A product detail page	collection, recommender
basket	The basket page	recommender
checkout	A step of the checkout flow	recommender
order_confirmation	The post-purchase page	recommender
error_page	A 404 or error recovery page	recommender
email	Results embedded in an email	recommender
chat	Your own conversational UI	any
mcp_agent	An agent calling over MCP	any

Four things follow from this:

• The touchpoint never changes ranking. Behaviour belongs to the surface; the touchpoint only records where the answer went, so a reporting change never moves your results.
• Sending it is optional. A request that omits it is served identically, and the only loss is that its results cannot be told apart from another placement’s in reporting. Send it wherever you know where the results are going.
• Each endpoint accepts only the touchpoints its intent serves, so the value set differs per endpoint: /collection has no basket, /search no homepage, and /recommender accepts all thirteen. The set each one takes is in its reference page and in the OpenAPI schema, so a generated client never offers a value that endpoint would refuse. A value outside an endpoint’s set is rejected with 422.
• One page routinely issues several requests that share a touchpoint and differ in intent: a results page carries both the search results and a recommendation strip, both at serp.

Example

An organization can have English and German catalogs. Each catalog can expose a channel for its storefront market. The English channel can power a search results surface and a recommendation surface, while the German channel uses equivalent surfaces over localized catalog content.

Data flow

1. Source records are mapped and indexed as canonical objects in a catalog.
2. A channel determines which catalog objects and attributes are available to a storefront or market.
3. A surface runs a discovery experience against that channel.
4. A widget calls the surface and renders the results to a visitor.

See also

• Identifiers — the prefixed IDs for every entity above
• Catalog object model — the shape of an indexed object
• Object types and relationships — what a catalog can hold besides products
• Discovery overview — calling a surface
• Authentication — how a channel is bound to a credential