Core Concepts

Core Concepts

Understanding the architecture and key ideas behind Produck SDK.

Architecture Overview

Produck SDK connects your frontend with an AI backend to create intelligent website experiences.

┌─────────────────────────────────────────────┐
│                  Your Website                │
│                                             │
│  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Chat Widget  │  │  SDK Core           │  │
│  │ (UI)         │  │  - DOM Extractor    │  │
│  │              │  │  - API Handler      │  │
│  └──────┬───────┘  └──────────┬──────────┘  │
│         │                     │              │
└─────────┼─────────────────────┼──────────────┘
          │                     │
          ▼                     ▼
┌─────────────────────────────────────────────┐
│            Produck Backend                   │
│                                             │
│  ┌──────────┐  ┌───────────┐  ┌──────────┐ │
│  │ Chat API  │  │ Knowledge │  │ API      │ │
│  │ (GPT-4o)  │  │ Base      │  │ Proxy    │ │
│  │           │  │ (Qdrant)  │  │          │ │
│  └──────────┘  └───────────┘  └──────────┘ │
└─────────────────────────────────────────────┘

Key Components

1. SDK Projects

SDK Projects are the top-level organizational unit.

  • Belong to an organization
  • Have a unique SDK key for authentication
  • Configure knowledge base, API schema, and DOM context
  • Independent from each other

2. Knowledge Base

The knowledge base stores information about your product as vector embeddings.

Sources:

  • Website URLs (crawled via Firecrawl)
  • Sitemaps
  • Uploaded documents (PDF, DOCX, TXT)
  • Raw text

Retrieval: When a user asks a question, the backend performs vector search to find relevant content and injects it into the AI's context.

Learn more →

3. API Schema

Provide an OpenAPI/Swagger schema and the AI can understand and execute your API endpoints.

Flow:

  1. SDK loads schema on init
  2. Endpoint summaries are sent with each chat message
  3. AI identifies the right endpoint when the user requests an action
  4. SDK executes the call (client-side or via proxy)
  5. Result is returned to the AI for confirmation

Security: Only whitelisted endpoints can be called.

Learn more →

4. DOM Context

The AI can read the current page on demand to answer page-specific questions.

Key design decisions:

  • On-demand only — content is never sent automatically
  • Selector scoping — control what the AI can read
  • No persistence — extracted content is used once and discarded

Learn more →

5. Chat Widget

A pre-built, customizable chat interface that handles:

  • Message display and input
  • Typing indicators
  • API call result rendering
  • Mobile responsiveness
  • Theme customization

Learn more →

Authentication Model

SDK Key (Public)

The SDK key identifies your project. It's safe to embed in client-side code.

<ProduckProvider sdkKey="pk_live_..." />

API Authentication (Private)

For API calls, authentication is handled separately:

TypeHow It Works
CookieBrowser cookies sent automatically (same-origin)
BearerToken added to Authorization header
API KeyCustom header added to requests

Data Flow

Chat Message Flow

1. User types message
2. SDK optionally extracts DOM context (if AI requests it)
3. Message + context sent to backend
4. Backend retrieves relevant knowledge base chunks
5. Backend builds AI prompt with: message + knowledge + API schema + DOM context
6. GPT-4o generates response
7. If response contains API call → SDK executes it → result sent back
8. Final response displayed to user

API Call Flow

1. AI identifies needed API call from schema
2. SDK checks endpoint against whitelist
3. SDK attempts client-side fetch
4. If CORS error → SDK retries via server proxy
5. Result returned to AI for confirmation message

Next Steps

InstallationKnowledge Base