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

# Architecture

> System architecture, data flow, and design decisions

## Multi-Tenant Architecture

VIZOCHOK is a multi-tenant SaaS where each tenant (retailer) gets an isolated environment with their own:

* Product catalog and vector embeddings
* AI configuration (LLM model, system prompt, disabled tools)
* API keys (public and secret)
* Webhook endpoints (products, cart)
* Usage limits and billing
* Admin users

All tenants share the same infrastructure but data is strictly isolated at every layer.

<CardGroup cols={2}>
  <Card title="Tenant A">
    * Catalog + Embeddings
    * API Keys (pk\_, sk\_)
    * LLM Config (configurable per tenant)
    * Webhooks (products, cart)
    * Usage Limits + Billing
    * Admin Users
  </Card>

  <Card title="Tenant B">
    * Catalog + Embeddings
    * API Keys (pk\_, sk\_)
    * LLM Config (configurable per tenant)
    * Webhooks (products, cart)
    * Usage Limits + Billing
    * Admin Users
  </Card>
</CardGroup>

## Data Flow

The complete data flow from a user message to a response:

<Steps>
  <Step title="Widget SDK (Storefront)">
    Customer sends a message via WebSocket connection.
  </Step>

  <Step title="VIZOCHOK Backend">
    WS Handler authenticates and checks rate limits. Shopping Agent (LLM + Tools) processes the request using Hybrid Search and Webhook Calls.
  </Step>

  <Step title="Client Backend">
    VIZOCHOK calls your Products API and Cart API via HTTP webhooks to get live prices and confirm cart operations.
  </Step>

  <Step title="Streaming Response">
    Results stream back to the Widget SDK via WebSocket events. Data is persisted to the database and cache.
  </Step>
</Steps>

### Step-by-Step Flow

1. **User sends a message** via the Widget SDK over WebSocket
2. **API server authenticates** the connection using the API key
3. **Rate limits are checked** at three tiers: per-connection, per-user, per-tenant
4. **Agent is initialized** with tenant config, session state, and user profile
5. **AI processes the message** using a tool-based architecture:
   * Search tools: Hybrid search across the product catalog
   * Cart tools: Add, remove, update, clear -- each calls the client's webhook
   * UI tools: Show products, ask user, show recipe checklist, show meal plan
6. **Prices are fetched** from the client's backend via the products webhook (server-to-server)
7. **Cart operations** call the client's cart webhook, which confirms or rejects
8. **Results stream back** to the widget via WebSocket as `text_delta`, `product_cards`, `cart_changed`, etc.
9. **Session is saved** for the next message

## What VIZOCHOK Stores vs. What the Client Stores

Understanding the data boundary is critical for integration:

### VIZOCHOK Stores

| Data                 | Storage         | Purpose                                                                    |
| -------------------- | --------------- | -------------------------------------------------------------------------- |
| Product catalog      | Database        | Names, descriptions, categories, images, SKUs -- for search and embeddings |
| Product embeddings   | Vector database | Vector embeddings for semantic search                                      |
| Conversation history | Database        | Full chat log for analytics and session restore                            |
| Session state        | Cache           | Cart, pending tools, conversation context                                  |
| API keys (hashed)    | Database        | Authentication                                                             |
| Tenant configuration | Database        | LLM, webhooks, limits, prompts                                             |
| Usage counters       | Cache           | Rate limiting and billing                                                  |
| User profiles        | Database        | Language, dietary preferences, favorite brands                             |

### Client Stores

| Data                     | Purpose                                          |
| ------------------------ | ------------------------------------------------ |
| Product **prices**       | Returned via `products_url` webhook on demand    |
| Product **availability** | Returned via `products_url` webhook on demand    |
| Shopping **cart**        | Managed via `cart_url` / `cart_get_url` webhooks |
| User identity            | Passed as `userId` to the widget                 |
| Order history            | Never shared with VIZOCHOK                       |
| Payment information      | Never shared with VIZOCHOK                       |

<Info>
  VIZOCHOK intentionally does **not** store prices or availability. These are always fetched in real-time from the client's backend via webhooks, ensuring the AI always has current data.
</Info>

## Session Lifecycle

<CardGroup cols={2}>
  <Card title="New Connection">
    1. Client sends `auth` message
    2. Server responds with `auth_ok`
    3. Server sends `conversation_started` with new `conversation_id`
    4. Message loop begins
    5. On disconnect, session saved server-side
  </Card>

  <Card title="Reconnection">
    1. Client sends `auth` message
    2. Server responds with `auth_ok`
    3. Server sends `session_restored` with cart + pending tools
    4. Message loop resumes
    5. On disconnect, session saved server-side
  </Card>
</CardGroup>

### Session Details

* **Server side**: Sessions are cached server-side and expire after a period of inactivity. On reconnect, the server restores cart state and pending tools.
* **Client side**: `sessionStorage` (per-tab) stores conversation ID and message history under key `vz-session-{storeId}`
* **On expiry**: After a period of inactivity, the session expires and a new conversation starts

## Smart Model Routing

VIZOCHOK uses a dual-model strategy to balance quality and cost:

* A **complex model** handles the first message in each conversation for accurate intent understanding
* A **fast model** handles subsequent tool-chain iterations for responsive, cost-effective processing

This approach typically reduces AI costs by 60-70% compared to using a single model. Both models are configurable per tenant via the Admin Panel.

Each conversation also has a configurable token budget. When the limit is approaching, the assistant suggests starting a new conversation.

## Agent Tool Architecture

The AI agent uses a tool-based architecture where the AI decides which tools to call based on the conversation:

### Non-Interactive Tools

These tools execute in the background and return results to the AI for further processing:

| Category | Description                                               |
| -------- | --------------------------------------------------------- |
| Search   | Searches your product catalog using hybrid search         |
| Cart     | Add, remove, update, clear cart items (via your webhooks) |
| Details  | Retrieve detailed product information                     |

### Interactive Tools

These tools render UI in the widget and pause for user input:

| Tool             | Widget UI                                      |
| ---------------- | ---------------------------------------------- |
| Product display  | Product cards with quantity steppers           |
| Quick replies    | Suggestion buttons for the user to choose from |
| Recipe checklist | Checkable ingredient list with submit button   |
| Meal plan        | Multi-day plan with approve/modify options     |

## Hybrid Search

Product search combines multiple strategies for high relevance:

* **Semantic search** -- understands meaning and intent, not just keywords
* **Full-text search** -- matches exact words and phrases
* **Fuzzy matching** -- handles typos, transliterations, and brand name misspellings

Results from all strategies are fused together and optionally re-ranked for improved relevance. Search and ranking providers are configurable per tenant.

After search, VIZOCHOK calls your [products webhook](/webhooks/products) to fetch real-time prices and availability. Products not returned by the webhook are filtered out.

## Webhook Architecture

VIZOCHOK uses server-to-server webhooks for all commercial data:

* **Products webhook** -- returns prices and stock for requested SKUs
* **Cart webhook** -- confirms cart operations (add, remove, update, clear)
* **Cart GET webhook** -- returns current cart contents at session start

All webhook requests include an HMAC-SHA256 signature for verification. See [Webhooks](/webhooks/overview) for full details.

## Error Handling

Errors flow through the system as machine-readable codes:

1. Backend detects error (rate limit, validation, LLM failure)
2. Backend sends `{"type": "error", "code": "rate_limit_exceeded"}` via WebSocket
3. SDK maps the code to a localized message using its i18n dictionary
4. SDK renders the error in the chat and fires the `onError` callback
5. The host page can handle the error (e.g., show a toast, log to analytics)

See [Error Codes](/concepts/error-codes) for the full list.