Skip to main content

​
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

​
Client Stores

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:

​
Interactive Tools

These tools render UI in the widget and pause for user input: 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.