Help centers, AI-native search with embeddings, embeddable in-app widgets, and the multi-language strategy that separates a real KB from a shared Notion page.
Research-based methodology. This guide synthesizes pgvector documentation, Anthropic’s contextual retrieval research, public Helpjuice / Document360 / Zendesk Guide architecture writeups, and our own builds with Claude. Where we have first-person experience we say so; otherwise we’re working from public sources. How we research.
Help centers were a mature category in 2020. Then GPT happened, and the entire shape of “what does good search look like in a help center” changed overnight. Customers no longer want a list of articles — they want an answer with citations. Most established KB tools (Helpjuice, Document360, Zendesk Guide) bolted AI on top of their existing search. None of them rebuilt around it. That’s the wedge.
This guide is for someone who wants to ship a real, paid knowledge-base product in 4–8 weeks using Claude as their build partner. We’ll skip the obvious (an article editor and a sidebar of categories) and focus on the load-bearing parts: hybrid AI + keyword search, retrieval-augmented answer generation with grounding, the embeddable widget that lives inside your customer’s app, and a multi-language strategy that doesn’t fall apart on the first non-English customer. If you want the broader build playbook first, our How to build a SaaS with Claude guide covers the general scaffolding workflow this one builds on top of.
Honest read: Helpjuice, Document360, Zendesk Guide, Intercom Articles, HelpScout Docs, and a dozen smaller competitors already exist. Each has years of feature accumulation. Each has switching costs (your customer has 400 articles already written somewhere). You will not out-feature them in year one. Three real wedges where solo founders win:
Pick one. Talk to ten support managers in that wedge before you ship.
The data model is medium-complex. The trick is the hierarchy: workspaces have categories, categories have sections, sections have articles. Some KBs go three levels, some two. You want a model that supports both without a schema change.
I'm building a knowledge-base SaaS like Helpjuice / Document360. The model needs to support: - Workspaces (my customers) with multiple admin users - A hierarchy of categories > sections > articles, OR a flat categories > articles model — configurable per workspace - Each article has: title, slug, body (markdown OR rich JSON), status (draft, published, archived), author, tags, locale - Articles can have multiple translations (one row per locale, linked by translation_group_id) - Public KB visibility per workspace: open, private (login required), hybrid (some articles open, some restricted) - A search_log table for analytics (query, result_clicks, no_result) - An article_feedback table for thumbs-up/thumbs-down per article - An embeddings table for AI search (one row per chunk per article, using pgvector) Design the complete Postgres schema. For every table give me: - Columns with types and constraints - A `path` materialized column on articles that stores the full category/section path as a slash-delimited string for fast breadcrumb rendering and SEO URLs (kept in sync via trigger) - pgvector extension setup and the embeddings table with an HNSW index - Indexes for: list articles in a category, full-text search via tsvector, vector search via pgvector - Triggers that update path when categories rename and update tsvector + queue embedding regen when article body changes Then write Supabase RLS for the three visibility modes and a security-definer function for the public render that respects visibility per article. Output as one SQL file I can run in the Supabase SQL editor.
The denormalized path column is the unobvious bit. Without it, every article render does a recursive join to compute “Getting Started > Setup > Installing the CLI” for the breadcrumb. With it, breadcrumb rendering is one string read and your SEO URLs (/help/getting-started/setup/installing-the-cli) come for free. The trigger to keep it in sync is the part Claude will get wrong on the first pass — insist on it cascading when a parent renames. The Supabase vs Firebase comparison covers why pgvector + tsvector in one Postgres is the right default for this stack.
Search is the entire differentiator for a 2026 KB. The bar customers expect: ask a natural question, get a paragraph answer, see the article citations underneath. Anything less feels like 2018 software.
The right architecture is hybrid: keyword search via Postgres tsvector for exact-match results, semantic search via pgvector embeddings for conceptual matches, then rerank or merge the two and feed the top results into Claude (or another LLM) for a grounded answer.
Build the AI search endpoint for my KB SaaS.
Architecture:
- POST /api/search { workspace_id, query, locale }
- Step 1: chunk-level retrieval
- Run BOTH a tsvector keyword search AND a pgvector semantic search
against the embeddings table for this workspace + locale
- Merge the results: take top 8 from each, dedupe by article_id,
rerank by combined score (alpha * keyword_score + (1-alpha) *
cosine_similarity, alpha=0.4 default but configurable)
- Take top 6 chunks
- Step 2: answer generation
- Build a prompt that includes the user's question AND the top 6
chunks with article titles and chunk text
- Send to Claude (haiku or sonnet by tier) with a system prompt that
enforces: "Only answer from the provided sources. If the sources
don't cover the question, say so. Cite the source article id for
every claim."
- Stream the response back to the client via SSE
- Step 3: post-process
- Parse out the cited article ids from the response
- Return the streamed text PLUS structured citations (article id,
title, slug, snippet)
Embedding generation pipeline:
- A trigger or queue worker that on article body change:
- Splits the body into ~512-token chunks with 50-token overlap
- Generates embeddings via voyage-3 OR text-embedding-3-small
(recommend voyage for retrieval quality)
- Upserts chunks into the embeddings table with HNSW index
- Soft-deletes old chunks for that article
Ground every answer. NEVER let the LLM answer from its own knowledge
when the retrieval is empty — instead return a clear "I don't have
information about that in this knowledge base" response.
Output: the search route, the embedding worker, the chunk splitter,
and the system prompt. Use streaming responses end-to-end.
Two non-obvious wins: (a) include the article title in the embedded chunk text, not just the body — titles are heavily semantically loaded and improve retrieval markedly; (b) use Anthropic’s contextual retrieval pattern where each chunk is rewritten to include 1–2 sentences of surrounding context before embedding. It’s a 2–5x improvement on retrieval quality for a one-time embedding cost. Our broader review of how to build an AI chatbot SaaS covers the prompt patterns for grounded answer generation in more depth.
Most customers don’t want their users to leave the app to find help. The embeddable widget is the feature that puts your KB inside your customer’s app: a help icon that opens a search box and answer interface in a slide-over panel. This is where you displace Intercom Articles and HelpScout Beacon for new customers.
Build the embeddable in-app widget for my KB SaaS.
DELIVERABLE 1 — the customer's snippet:
<script>
window.__kb = {
workspaceId: 'wks_abc',
user: { id: 'u_42', email: 'pat@cust.com' },
locale: 'en',
primaryColor: '#7FD4A8'
};
(function(){
var s=document.createElement('script');
s.src='https://cdn.kbapp.com/widget.js';
s.async=true;
document.head.appendChild(s);
})();
</script>
DELIVERABLE 2 — widget.js (vanilla JS, ~8KB gzipped):
- Reads window.__kb config
- Injects a floating help button in bottom-right (configurable)
- On click, opens a slide-over iframe at
https://app.kbapp.com/embed?ws=...&locale=en
- Forwards the user identity to the iframe via postMessage AFTER the
iframe sends a "ready" signal
- Exposes window.kb.open(), window.kb.close(),
window.kb.searchFor("how to do X")
- Listens for an "escalate" event (when a user clicks "Talk to support")
and bubbles to the host page so the customer can route to their
ticket system
DELIVERABLE 3 — the embed page at /embed:
- Layout: search box at top, results below
- As the user types, debounced calls to /api/search render results
- The AI answer streams in above the article list
- Each citation chip is clickable, expanding the article inline
- A "Was this helpful?" footer per article that posts to the feedback
endpoint
- A "Talk to a human" button at the bottom that postMessages the host
page
Cover security: same-origin postMessage source check (allow embedding
ONLY on domains the workspace has whitelisted), CSRF on feedback and
search endpoints, rate-limit per workspace per IP.
The whitelist enforcement matters: without it, anyone can embed your widget on any site using your customer’s workspace ID, scraping their content. Require workspace admins to add allowed domains in settings, then validate the iframe’s parent origin via postMessage handshake. Vibe-coding tools like Cursor and Lovable generate widget snippets quickly but consistently miss this domain-whitelist step — review the security boundary by hand.
The thumbs-up / thumbs-down on each article is feature parity table-stakes. The differentiator is what you do with that data. Most KBs surface it as a per-article number that nobody acts on. The right pattern is to aggregate it into actionable signal: which articles need rewriting, which categories have low helpfulness, which queries return unhelpful answers.
Build the feedback aggregation system for my KB SaaS.
Data:
- article_feedback rows: article_id, locale, vote (1 or -1), reason
(optional free-text), timestamp, anonymous_fingerprint
- search_log rows: query, result_article_ids, clicked_article_id,
zero_results (bool), timestamp
Build three reports for the workspace admin dashboard:
1. Articles needing attention
- Sort by negative feedback rate over the last 30 days, weighted by
view count
- For each, show: article title, total views, helpful_rate, top 3
reason text snippets (if any), suggested action
- Suggested action via Claude prompt: take the article body + the
reason snippets and recommend one of (rewrite, add example,
split into two, mark out of date)
2. Search gaps
- Group search_log entries by normalized query (lowercase, stem,
embedded similarity cluster)
- Surface clusters where: zero_results=true frequency > 20%, OR
the clicked article had thumbs-down rate > 40%
- For each gap, show: representative query, count, suggested action
(write a new article, expand existing X, add synonym to article Y)
3. Article health score (0-100 per article)
- Formula: blend of helpful_rate, recency, view count percentile,
and an "AI freshness check" that asks Claude whether the article
mentions outdated UI/feature names by passing the article body
and the workspace's product name + recent changelog
Output: the SQL for the feedback aggregation, the workspace admin
dashboard pages with the three reports, the Claude prompts for the
suggested actions and freshness check. Run as a nightly cron, store
results in a `kb_health_reports` table for instant dashboard load.
The “search gaps” report is the highest-value output of the entire product. A workspace admin who sees “47 customers asked some variant of ‘how do I cancel my subscription’ this month and we have no article on it” will write that article that day — and that’s deflected support tickets that justify your subscription forever. Make this report the first thing they see when they log in.
The moment you sell to a customer with an international audience, you’re a multi-language KB. Most established tools force a hard choice: either every article is translated or it’s English-only. The reality is messy — customers will translate the top 50 articles into Spanish and French, leave the next 200 in English, and want the search/widget to do the right thing.
Implement multi-language support for my KB SaaS. Schema (already covered in step 1): - articles.locale text not null (BCP-47 like 'en', 'es', 'fr') - articles.translation_group_id uuid (siblings across locales share this id) - workspaces.default_locale text not null - workspaces.supported_locales text[] not null Search behavior: - A user query arrives with a locale (from widget config or accept- language header) - Step 1: search ONLY in that locale's embeddings + tsvector - Step 2: if results < 3, expand search to the workspace's default_locale - Step 3: if a result article exists in BOTH the user's locale and the default locale, prefer the user's locale version - Step 4: when generating the AI answer, instruct Claude to respond in the user's locale even if the source articles are in a different locale (with a footnote indicating the source language) Editor flow: - When an admin opens an article, show a locale switcher with all supported locales - Locales without a translation show a "Translate from English" button that pre-fills with a Claude-generated draft (admin reviews + edits) - A "Translation status" dashboard showing translation coverage per category and locale Public rendering: - The KB URL pattern is /[workspace-slug]/[locale]/[article-path] with /[workspace-slug]/[article-path] redirecting to the user's preferred locale based on cookie or accept-language - Hreflang tags on every page pointing to all sibling translations - Sitemap includes one entry per locale per article Output: the search-with-fallback function, the translation editor UI, the AI translation draft prompt, the URL routing middleware, and the hreflang component.
The translation-draft pattern is the underrated part. A workspace admin who can click “translate to Spanish” and get a 90%-correct draft they edit in 5 minutes will translate 200 articles. Without that, they translate 12. Building AI features into SaaS covers the broader prompt-engineering patterns that apply here.
Per-workspace tiers anchor this category cleanly:
The AI search feature is the primary upgrade trigger from Starter to Growth. Most customers will tolerate a slow keyword search; nobody tolerates an AI answer that hallucinates. Spend disproportionate engineering time on grounding (refusing to answer when retrieval is empty) and citation rendering (showing the user exactly which article each claim came from). These are the things that justify the price differential.
Distribution lever in this category: a “Powered by” link in the public KB footer of free / Starter tier customers. KB pages are heavily indexed by Google — one customer with a 200-article KB drives meaningful organic backlinks. Don’t remove this from any tier below $99/month. Browse our list of AI-adjacent SaaS build guides for related categories where the same retrieval-augmented patterns apply.
A KB tool where the primary interface is grounded AI search with citations — not a search list with a chat tab bolted on — is the wedge for 2026. Pair that with vertical specificity (devtools, healthtech, integrations) or deep helpdesk integration (HelpScout, Front, Zendesk), and per-workspace tiers up to $499/month are reachable. Pick a wedge, talk to ten support managers, ship the AI search before the editor.
The stack, prompts, pricing, and mistakes to avoid — for solo founders building with AI.