Skip to main content

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.

​
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.

Tenant A

  • Catalog + Embeddings
  • API Keys (pk_, sk_)
  • LLM Config (configurable per tenant)
  • Webhooks (products, cart)
  • Usage Limits + Billing
  • Admin Users

Tenant B

  • Catalog + Embeddings
  • API Keys (pk_, sk_)
  • LLM Config (configurable per tenant)
  • Webhooks (products, cart)
  • Usage Limits + Billing
  • Admin Users

​
Data Flow

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

Widget SDK (Storefront)

Customer sends a message via WebSocket connection.
2

VIZOCHOK Backend

WS Handler authenticates and checks rate limits. Shopping Agent (LLM + Tools) processes the request using Hybrid Search and Webhook Calls.
3

Client Backend

VIZOCHOK calls your Products API and Cart API via HTTP webhooks to get live prices and confirm cart operations.
4

Streaming Response

Results stream back to the Widget SDK via WebSocket events. Data is persisted to the database and cache.

​
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

DataStoragePurpose
Product catalogDatabaseNames, descriptions, categories, images, SKUs — for search and embeddings
Product embeddingsVector databaseVector embeddings for semantic search
Conversation historyDatabaseFull chat log for analytics and session restore
Session stateCacheCart, pending tools, conversation context
API keys (hashed)DatabaseAuthentication
Tenant configurationDatabaseLLM, webhooks, limits, prompts
Usage countersCacheRate limiting and billing
User profilesDatabaseLanguage, dietary preferences, favorite brands

​
Client Stores

DataPurpose
Product pricesReturned via products_url webhook on demand
Product availabilityReturned via products_url webhook on demand
Shopping cartManaged via cart_url / cart_get_url webhooks
User identityPassed as userId to the widget
Order historyNever shared with VIZOCHOK
Payment informationNever shared with VIZOCHOK
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.

​
Session Lifecycle

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

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

​
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:
CategoryDescription
SearchSearches your product catalog using hybrid search
CartAdd, remove, update, clear cart items (via your webhooks)
DetailsRetrieve detailed product information

​
Interactive Tools

These tools render UI in the widget and pause for user input:
ToolWidget UI
Product displayProduct cards with quantity steppers
Quick repliesSuggestion buttons for the user to choose from
Recipe checklistCheckable ingredient list with submit button
Meal planMulti-day plan with approve/modify options
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 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 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 for the full list.