> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinrefine.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understanding the fundamentals of Refine

## Visual Search

Traditional e-commerce search matches keywords. Refine understands what products *look like*.

When you search for "floral midi dress," Refine:

1. **Understands the text** — semantic understanding of "floral," "midi," and "dress"
2. **Analyzes visual features** — patterns, colors, silhouettes from product images
3. **Combines both signals** — the `visualWeight` parameter controls the balance

```typescript theme={null}
// Text-heavy search (specs matter more)
const results = await refine.search.text({
  query: 'laptop 16gb ram',
  visualWeight: 0.2  // 80% text, 20% visual
});

// Visual-heavy search (appearance matters more)
const results = await refine.search.text({
  query: 'boho summer dress',
  visualWeight: 0.7  // 30% text, 70% visual
});
```

## Catalogs

A **catalog** is a collection of products that share a search index. Most stores have one catalog, but you might use multiple for:

* Separate indexes per locale (US, EU, APAC)
* B2B vs B2C product sets
* Multiple brands under one organization

Each catalog has a unique ID used in SDK initialization:

```typescript theme={null}
const refine = new Refine({
  catalogId: 'cat_us_retail_2024'
});
```

## Visual Embeddings

When you upload a product, Refine generates a **visual embedding** — a numerical representation of what the product looks like. These embeddings power:

* **Visual similarity** — finding products that look alike
* **Image search** — matching uploaded photos to your catalog
* **Visual weight** — the visual component of text search

Embeddings are generated automatically. You don't need to manage them directly.

## Surfaces and Sources

When tracking events, you specify **where** the products appeared and **how** they got there.

### Surface

The UI location where products are displayed:

| Surface          | Description                         |
| ---------------- | ----------------------------------- |
| `search_results` | Main search results page            |
| `product_page`   | Product detail page recommendations |
| `home_page`      | Homepage recommendations            |
| `cart_page`      | Cart page cross-sells               |
| `category_page`  | Category/PLP pages                  |
| `checkout`       | Checkout page suggestions           |

### Source

How the products were generated:

| Source          | Description                     |
| --------------- | ------------------------------- |
| `text-search`   | Text search results             |
| `image-search`  | Image search results            |
| `similar-items` | Similar product recommendations |
| `visitor-recs`  | Visitor-based recommendations   |
| `user-recs`     | User-based recommendations      |
| `plp`           | Product listing page            |

```typescript theme={null}
const context = refine.events.trackItemsServed({
  surface: 'product_page',
  source: 'similar-items',
  itemIds: productIds
});
```

## Identity Hierarchy

Refine tracks three levels of identity:

<Steps>
  <Step title="Visitor ID">
    Auto-generated, persisted in localStorage. Survives sessions but not device changes. Every user starts as a visitor.
  </Step>

  <Step title="Session ID">
    Auto-generated per browsing session. Expires after 30 minutes of inactivity (configurable).
  </Step>

  <Step title="User ID">
    Your identifier, set via `refine.identify()`. Links visitor behavior to a known user account.
  </Step>
</Steps>

```typescript theme={null}
// Anonymous visitor browsing
const visitorId = refine.getVisitorId(); // Auto-generated

// User logs in
refine.identify('user_12345');

// Now visitor history is linked to user_12345
const recs = await refine.recs.forUser({ configId: 'config_abc' });
```

## Recommendation Strategies

Refine supports three recommendation types:

### Similar Items

Find products visually and contextually similar to a specific product. Best for product detail pages.

```typescript theme={null}
const recs = await refine.recs.similarItems({
  anchorId: 'sku_dress_001',  // The product being viewed
  topK: 8
});
```

### Visitor Recommendations

Personalized suggestions based on the current visitor's browsing behavior. No login required.

```typescript theme={null}
const recs = await refine.recs.forVisitor({
  configId: 'homepage_recs',
  topK: 12
});
```

### User Recommendations

Deep personalization based on a logged-in user's full history across sessions and devices.

```typescript theme={null}
refine.identify('user_12345');
const recs = await refine.recs.forUser({
  configId: 'you_may_like',
  topK: 12
});
```

## ServeContext Pattern

The SDK uses a **ServeContext** pattern for event tracking. When products are displayed, you get a context object that tracks subsequent interactions:

```typescript theme={null}
// Products are served
const context = refine.events.trackSearch(query, results.results, options);

// User interacts
context.trackClick(productId, position);    // They clicked
context.trackView(productId, position);     // It became visible
context.trackAddToCart(productId);          // They added to cart
```

This pattern ensures all interactions are correctly attributed to the original search or recommendation serve.

## Next Steps

<CardGroup cols={2}>
  <Card title="Glossary" icon="book" href="/getting-started/glossary">
    Full terminology reference
  </Card>

  <Card title="SDK Overview" icon="code" href="/sdk/overview">
    Start building with the SDK
  </Card>
</CardGroup>