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.
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 widget layer. It renders results and forwards approved interaction signals, such as clicks and purchases, for analytics and ranking.

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 scope, such as a category	POST /discovery/v1/collections	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.

You can configure several surfaces with the same intent for different placements: a homepage recommender and a cart recommender are two surfaces, tuned independently.

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 homepage 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