Chat UX

For frontend developers. The behaviour of ChatBotComponent.vue and its satellite dialogs: the streaming send, the confidence chip, the grounding warning, the feedback dialog, and save / export flows.

Prerequisites

• Read State Management — the auth module owns the access token used in the streaming request.
• Keycloak access token present (the chat window will not render the input until currentUser is truthy).
• The backend BFF exposes POST /api/queries/stream (SSE) and POST /api/queries/{queryId}/feedback. See Backend API Contracts.

Chat window anatomy

src/components/ChatBotComponent.vue is the main chat surface. From top to bottom:

The message list scrolls automatically: a messagesEnd ref is mutated whenever the messages array changes. Manually scrolled-up content stays put until the user scrolls back to the bottom (no auto-jank on long histories).

Streaming send

The send path is input → chatbotService.submitQueryStream() → POST /api/queries/stream (SSE) and back. The service uses fetch directly (axios cannot stream), creates an AbortController, and dispatches each data: SSE frame to a typed callback.

// chatbotService.submitQueryStream signature
submitQueryStream(queryData, { onChunk, onMetadata, onTranslation, onDone, onError }) → AbortController

// Caller (ChatBotComponent)
this.streamController = chatbotService.submitQueryStream(
  { message: text, context: this.selectedContextItems, conversationId: this.currentChatId },
  {
    onChunk: (content) => { /* append to last bot message */ },
    onMetadata: (meta) => { /* confidence + is_grounded */ },
    onTranslation: (content) => { /* streaming translation in target locale */ },
    onDone: (data) => { /* finalize + persist */ },
    onError: (err) => { /* show toast, mark message failed */ }
  }
);

Behaviour during the stream

Cancellation: starting a new send

When the user submits a new message while a stream is in flight, ChatBotComponent calls this.streamController.abort() before opening the new stream. The previous fetch fails with AbortError; the service’s catch branch suppresses it (if (error.name === 'AbortError') return;) — only the new stream’s events drive the UI.

Markdown rendering and sanitisation

Bot messages render Markdown to HTML and pipe through DOMPurify:

// ChatBotComponent.vue (~line 696)
renderMarkdown(content) {
  if (!content) return '';
  const html = marked.parse(content);
  return DOMPurify.sanitize(html);
}

Two customisations matter:

1. Tight-list renderer override — GFM lists are emitted as <li><p>label</p><ul>...</ul></li> which produces double-spaced output. ChatBotComponent injects a custom tightListRenderer (via marked.use({ renderer })) so nested bullets render compact.
2. HTML sanitisation — DOMPurify.sanitize strips <script>, inline event handlers, and javascript: URLs before the HTML is inserted via v-html. User messages are never rendered as Markdown — they are shown as plain text only.

The combination means: even a prompt-injected response from the LLM cannot reach the page as raw HTML.

Confidence chip and grounding flag

Backend metadata arrives on the metadata SSE frame and is attached to the last bot message. The UI renders one of three states:

The chip and the grounding flag are mutually exclusive (v-if / v-else-if). The Sparkles warning is the visible signal that the answer was synthesised from the LLM’s general knowledge rather than retrieved from the knowledge base — important for public-sector deployments where hallucination risk must be flagged.

The confidence_score is the reranker-confidence mean from the RAG pipeline (Architecture → Confidence Scoring). It is not the LLM’s self-reported confidence (the [[CONF:NN]] sentinel) — those are different signals; only the reranker score flows to the UI chip.

How to interpret

• High confidence (≥ 80 %) — typically a strong match in the knowledge base.
• Low confidence (≤ 40 %) — answer is likely correct in form but weakly grounded. Don’t trust without domain expertise.
• Not grounded — treat as a general-LLM answer, regardless of how confident it sounds.

The chip is informational, not actionable. The user can always click the feedback button to rate the response and improve future ranking.

Feedback dialog

ChatResponseFeedbackDialog.vue opens per bot message when the user clicks the feedback button. Two columns:

Behaviour

• The user must select either a thumb or a rating before submitting — both are optional individually, but at least one is required (the Submit button is disabled otherwise).
• The skin-tone selector (thumbFeedback === 'up' ? skinToneColor : 'none') draws from a small palette stored on the component. Selection is NOT persisted across sessions — it lives on the dialog instance only.
• Comments are sanitised before submission (no HTML, length capped server-side).
• On submit: chatbotService.submitFeedback(queryId, { thumb, rating, comment }) — POST /api/queries/{queryId}/feedback. On success, the dialog closes and a toast appears. On failure, an inline error stays in the dialog.
• Ratings aggregate into the admin analytics satisfaction tiles — see Dashboards.

Save / export / new-chat flows

All three flows live inside ChatBotComponent.vue and share the same confirmation primitives.

Save chat

The default folder is default (All Chats); selecting a different folder triggers addChatToFolder and updates the sidebar selection.

Export

The Markdown → PDF converter handles only the LLM-emitted subset (paragraphs, lists, code, headings). Tables are flattened; embedded images are skipped. This is intentional — the export is meant for archiving a conversation, not a high-fidelity print.

New chat + load chat confirmations

Switching chats (or starting a new one) when the current chat has unsaved changes triggers ConfirmDialog:

The unsaved-state heuristic is purely client-side: any text in the input area that hasn’t been sent yet, or any change to context pills that hasn’t been persisted. There is no formal “draft” flag — the heuristic is conservative (false positives are cheap; false negatives lose work).

Quick-help overlay

The overlay appears on a fresh currentChatId (no prior messages) and when no context items are selected. The cards come from config.features.chat.quickHelp.buttons in the runtime config loaded by main.js (ChatBotComponent.vue:706-744), not from the backend. Display text and prompt text are resolved per locale via resolveConfigText(...).

A card click has two effects:

1. The card’s title populates the input area as a “prefilled prompt” (still requires the user to send). Title is resolved per locale.
2. The card’s action.hiddenPrompt is the actual LLM-facing prompt — action.visibleText is the friendly hint shown to the user; hiddenPrompt can be richer and is sent in the queryData payload.

Card config (each entry in config.features.chat.quickHelp.buttons):
{
  "id": "agriculture.subsidies",
  "title": "How do I apply for a farming subsidy?",
  "action": {
    "visibleText": "How do I apply for a farming subsidy?",
    "hiddenPrompt": "Explain the eligibility criteria, required documents, and processing time for the agriculture subsidy programme for smallholder farmers."
  },
  "service": "Agriculture",
  "serviceKey": "agriculture",
  "serviceLabels": ["agriculture", "subsidies", "rural-development"],
  "category": "agriculture",
  "icon": "agriculture.svg"
}

service is the localized display name; serviceKey / serviceLabels are the English KB labels used as the retriever filter. Display and filter are decoupled so the button always shows its localized title while the filter always uses English KB labels.

Accessibility

The skin-tone selector on the feedback dialog is keyboard-operable via click; each swatch has an aria-label like “Skin tone 1”, “Skin tone 2”, etc. (hardcoded in ChatResponseFeedbackDialog.vue:87, not i18n).

Failure modes & troubleshooting

Related

• State Management — chatHistory module that owns conversations and folder CRUD.
• UI Component Inventory — full list of chat-related components.
• Sidebar & Navigation — left-side conversation list, right-side related documents.
• Backend API Contracts — /api/queries/stream and /api/queries/{id}/feedback payloads.
• RAG Generation — how the backend produces confidence_score and is_grounded.