Skip to content
vviinn DocsDocs Beta

How It Fits Together

vviinn is made up of a few pieces that each play a distinct role. There are exactly four you ever access directly — the Widget (documentation), Panel, the Platform API, and the MCP server. Everything else — the search engine, the catalog, the AI models — is backend infrastructure none of these four talk to except through the same request/response contract each one exposes; you never call it directly, no matter which of the four you’re using.

flowchart LR
    subgraph Shopper
        A[vviinn Widget]
    end

    subgraph Integrations
        F[Platform API]
        G[MCP Server]
    end

    subgraph Merchant
        B[Panel]
    end

    subgraph Backend
        C[Search & Discovery Engine]
        D[Product Catalog]
        E[AI Models]
    end

    A -->|search, browse, recommendations| C
    F -->|search, recommendations| C
    G -->|search, recommendations, catalog discovery| C
    B -->|site & campaign configuration| C
    C -->|indexes and queries| D
    C -->|embeddings, detection, OCR| E
    D -->|ranked products| C

Everything outside the Backend box above is something you can access directly; everything inside it, you can’t — it’s only ever reached through one of the other four.

The pieces

Section titled “The pieces”

What you access directly

Section titled “What you access directly”

  • 🧩 vviinn Widget

    The front-end components embedded in your shop: the search bar, auto-suggest dropdown, product listing pages, and recommendation carousels shoppers actually interact with. Documented in the Widgets section, with an interactive Storybook playground — useful if you’re customizing how the widget looks or integrating it into a custom theme.

  • 🎛️ Panel

    Where you set up your site, connect your product feed, and configure each service — text search, visual search, recommendations, boosting, and more. Changes take effect immediately, no redeploy or waiting period. Also has a built-in AI Assistant for configuration questions while you work.

  • 🔌 Platform API

    A REST API some clients call directly to fetch search results and recommendations, for a custom front-end instead of the pre-built Widget. Lives at api.vviinn.com; full endpoint reference (the OpenAPI spec) is in the API Reference. Authenticates the same way as everything else, with your site’s API credentials.

  • 🤖 MCP Server

    Exposes search, recommendations, and catalog discovery as tools an AI agent can call directly, rather than as a REST API for a general-purpose app. Same API credentials as everything else — a read-only token for search/discovery tools, Basic auth for the memory tools.

Backend — not directly accessible

Section titled “Backend — not directly accessible”

Every request from any of the four pieces above eventually reaches these, but you never call them yourself:

  • ⚙️ Search & Discovery Engine

    The backend that receives every request from the Widget, Panel, Platform API, or MCP server, applies your campaign configuration, and returns ranked results.

  • 📦 Product Catalog

    Your product data, imported from the feed(s) you configure in Panel, kept in sync on the schedule you set.

  • 🧠 AI Models

    The embedding, image-recognition, and text-understanding models that power semantic search, visual search, and product data enrichment.