Resources · Reference architecture
The design we start from when a support team wants an assistant that answers from its help centre, cites the article it used, declines what its sources do not cover, and hands everything else to the helpdesk with the full conversation. It is a reference design, not a drawing of any client’s system: each box lists the options we choose between per project.
Layer: all four, centred on Know
The problem
Support teams rarely need a chatbot that knows everything. They need one that answers what the help centre already answers, says so when it cannot, and never invents a refund rule. The hard parts are keeping the index in step with the help centre, deciding when an answer is safe to send, and getting the rest into the helpdesk without the customer repeating themselves.
It suits teams with a maintained help centre and a helpdesk that has an API. It is the wrong start when answers live in people’s heads or most questions need account data; then the WhatsApp design with read-only lookups fits better.
Components
Takes the question from the widget or a help-centre page and keeps one conversation id across reloads.
What the assistant may answer from. Each source has a named owner and a visibility tag: public, signed-in or internal.
Splits sources along their headings, embeds only changed passages and retires the old version in the same step, so two copies of a policy are never live.
Passages with a keyword index, vectors, version and visibility.
Filters by what the customer may see, then fuses keyword and vector rankings, so exact product names and paraphrases both match.
Writes the reply from the retrieved passages only, in the customer’s language, with the passage ids it used.
Code, not a prompt: the reply must map to cited passages, retrieval must clear the topic’s threshold, and the topic must not be on the never-answer list. It fails closed.
Creates a ticket with the transcript, passages shown and reason, and tells the customer who will reply.
Each turn with its outcome, kept for your retention period; unanswered questions roll up into a weekly content backlog.
Data flow
How it works
Mechanism 01
Public articles, customer-only guides and internal notes can share one index because the visibility filter runs before ranking, not after. The model never sees a passage the customer could not open, so a clever question cannot pull an internal note into a public answer.
Simpler to reason about, but copies drift. We split only when audiences need different models or data regions.
Mechanism 02
If a reply cannot be tied to a passage, the customer gets a plain “that is not in our help centre” and an offer of a person. Thresholds are tuned per topic on the eval set, so billing can be held to a stricter bar than setup.
A higher answer rate, and the occasional confident wrong answer about your own policies.
Mechanism 03
A handoff is a helpdesk ticket, not a link to a contact form: transcript, passages shown, the reason the assistant stopped and any contact details given. Agents answer in the tool they already use, and the question joins the content backlog and the eval set.
Fine for a pilot, but it loses assignment and reporting.
Reference diagram
A customer question passes input checks to a hybrid retriever over an index of owner-approved help-centre content; the model drafts, and a citation check sends a cited answer to the customer or a ticket to your helpdesk, logging every outcome.
Diagram with 13 parts: Customer question (source), Content owner (human), Help-centre pages (source), Input checks (control), Ingestion job (processing), Hybrid retriever (processing), Search index (system of record), Answer model (model), Citation check (control), Conversation log (system of record), Customer (human), Support agent (human), Your helpdesk (system of record).
Connections:
Platform
Versioned ingestion, the hybrid retriever and the cite-or-decline rule.
Input checks, the never-answer list and the handoff with the transcript.
The eval set built from your real questions, which gates every change.
The widget adapter and the connection to your helpdesk.
Build or buy
| Option | Fits when | The trade-off |
|---|---|---|
| Turn on the helpdesk’s own bot | Your help centre lives in that helpdesk and its answers are good enough as they come. | Little control over thresholds, visibility or evaluation. |
| Build on this reference design | You need auditable citations, rules per topic, several sources or channels, or control over where data lives. | You own an index, an eval set and a small service. |
| Combine the two | Keep the helpdesk for tickets and agents; build retrieval, checks and the widget around its API. The shape we build most often. | Two systems to keep in step; the helpdesk API shapes the handoff. |
Rollout
Weeks 1–2
Choose sources, name owners, and build the first eval set from past tickets.
Weeks 2–4
Ingestion, retrieval, the citation check and the never-answer list, scored on the eval set.
Weeks 4–5
Tickets with transcripts; your agents try the widget and mark wrong answers.
Weeks 5–6
Live on a few pages, with the content backlog and an owner for declines.
After launch
More pages and channels; thresholds tuned on the eval set.
Failure modes
Running cost
Defaults
Limits
Configuration
assistant: support-help-centre
sources:
- id: help-centre
owner: support-lead
visibility: public
reindex: on-publish
- id: warranty-guides
owner: product-team
visibility: signed-in
retrieval:
mode: hybrid # keyword + vector, rank fusion
filter: visibility-before-rank
top_passages: 5
answer:
cite: required
on_low_confidence: decline-and-offer-person
never_answer: [refund-over-limit, legal, medical]
handoff:
target: helpdesk-api
include: [transcript, passages, reason, contact]
logging:
mask: [card-number, email]
retention_days: 30FAQ
It is where we start. At scoping we keep the boxes and pick the option inside each from your help centre, helpdesk, languages and data rules; you get a written component list to compare with this design.
Sometimes. If its search API returns passages with stable ids and can filter by audience, the retriever can call it. Most help-centre search returns whole articles ranked for browsing, which makes citations vague, so we usually index a copy kept in step on every publish.
An article update becomes a new version and the old one is retired in the same step, so both are never live. Publishing triggers the re-index, and a nightly comparison alerts the content owner if the index falls out of step.
A ticket with the transcript, the passages shown, the reason it stopped (no source, a never-answer topic, or the customer asked for a person) and any contact details given. Agents answer in the helpdesk as they do today.
Usually two people, part-time: a content owner who clears the weekly backlog of unanswered questions, and a support lead who reviews handoffs. Neither role writes code.
Not for help-centre answers. Account questions need a signed-in session and read-only lookups, which moves the design towards the agent pattern; many teams launch with public content and route those to a person.
Next step
Book a free 30-minute strategy call. Bring one process you want to automate and we will talk through scope, integrations and a sensible first step.
Free 30-minute call · no commitment