Core Concepts

KiBee is built around a few simple concepts. Understanding these will help you integrate effectively regardless of what your SaaS product looks like.

Targets

A target is any UI element in your product that KiBee can guide users to. You mark elements with data-kibee-id attributes and register them with the SDK.

Targets are identified by their kibeeId, not by CSS selectors. This means your targets survive redesigns, deploys, and framework changes. The bee always finds the right element.

Flows

A flow is a sequence of steps that guide a user through a multi-step workflow. Each step tells the bee what to do: fly to a target, wait for a click, wait for input, display a message, or celebrate completion.

Flows are defined as JSON and can be created via the Admin Console or the API. They're tied to a pageId so KiBee knows which flows are available on which page.

The Bee

The bee is a 3D animated character that flies to targets and guides users. It's rendered using Three.js and sits on top of your product as a lightweight overlay. The bee uses pointer-events: none so it never blocks clicks on your UI.

The bee has states:

• Idle — docked at the corner, waiting
• Guiding — actively flying between targets
• Thinking — processing intent or finding elements
• Celebrating — flow completed successfully

Sessions

A session represents one user's interaction with KiBee on your product. Sessions track which page the user is on, which flow is running, and the current step. Each session is linked to a visitor (identified by a persistent localStorage ID).

Honey & Sting

Honey bookmarks record successful paths — when a flow completes cleanly, the route can be saved so future users follow the same proven sequence.

Sting markers flag friction points — when a user stalls, abandons, or struggles at a step, that moment is recorded so product teams can fix the underlying UX problem instead of just re-guiding around it.

The Hive

The hive is your Admin Console — where support agents see all active user sessions, chat with users, push guidance flows, and monitor friction. Each workspace has its own hive showing only its data.

Workspaces

A workspace represents one website or product where KiBee is installed. Each workspace has its own API keys, flows, sessions, and settings. One account can have multiple workspaces (e.g., your main SaaS + mobile app).

Intent Matching

When a user asks KiBee a question (via kibee.ask()), KiBee uses semantic similarity to find the best matching flow. It embeds the user's query and compares it against flow embeddings using pgvector cosine similarity. If no good match is found, it falls back to phrase-based matching.