Frontend Debug Panel

The ZOL Intelligent Search frontend includes a real-time debug panel that exposes every pipeline step as visual badges. This is designed for academic evaluation — enabling examiners and developers to observe the complete RAG pipeline behavior during live demonstrations. The debug panel adopts Shneiderman's progressive-disclosure principle (Shneiderman et al. 2016, §13.3): end users see a clean, minimal progress indicator; admins see the full technical breakdown without leaving the chat surface.

How to Enable

The debug panel is controlled by a boolean flag on the PipelineProgress component. In admin mode, the chat interface automatically enables debug information, exposing all technical badges. End users see a clean, minimal progress indicator with only the stage name and percentage, while admins see the full technical breakdown including intent classification, retrieval strategy, search method, and evaluation scores.

Pipeline Stages & Badges

Each pipeline stage emits structured progress data via WebSocket. The debug panel renders this data as color-coded badges:

Stage	Badge	Color	Data Source
UNDERSTANDING	Intent type + confidence	Green	intent, intent_confidence
UNDERSTANDING	Retrieval strategy	Purple	retrieval_strategy
UNDERSTANDING	Query rewriting	Blue border	original_query, rewritten_query
SEARCHING	Document count	Blue	documents_found
SEARCHING	Search method	Orange	search_method (e.g., hybrid_bm25_vector)
SEARCHING	BM25 match count	Red	bm25_matches
SEARCHING	Canonical question matches	Pink	canonical_question_matches
ANALYZING	Context expansion	Cyan	chunks_retrieved → chunks_after_expansion
ANALYZING	Stage 5b — affinity rerank	Teal	affinity_top_category, affinity_n_chunks (when present)
ANALYZING	Stage 5c — doctor-list injection	Amber	doctor_list_injected (boolean; only emitted when triggered)
GENERATING	Progress indicator	Blue	progress_pct
EVALUATING	Overall score + grade	Green/Red	eval_overall_score, eval_grade
EVALUATING	Faithfulness	Indigo	eval_faithfulness
EVALUATING	Relevancy	Violet	eval_relevancy

Stage 5b and 5c badges expose the Value Framework post-retrieval rerank and the conditional doctor-list injection respectively. These stages always execute on every non-cached query, but Stage 5c emits a badge only when its trigger conditions fire (intent in {doctor_lookup, dept_or_service_lookup} plus a list-signal phrase plus a department hint).

Data Flow

Document Detail View

The Document Explorer displays enriched chunk metadata when viewing document details:

Chunk Metadata Badges

Each chunk in the detail view shows:

• Canonical Questions (blue pills): AI-generated questions that this chunk can answer, created during ingestion enrichment. These improve BM25 retrieval by matching user queries against these pre-computed question forms.
• Category (purple): The content category assigned during ingestion (e.g., conditions, treatments, administrative).
• Content Freshness (cyan): Whether the content is static, dynamic, or time_sensitive, used for recency boosting during retrieval.
• BM25 Indexed (green/gray): Whether a PostgreSQL tsvector search vector has been generated for this chunk, enabling hybrid BM25+vector retrieval.

Example

When viewing a chunk about "cardioversie" (cardioversion):

Chunk 3 of 12 | Page 2 | 287 tokens
────────────────────────────────────
[Content of the chunk...]

Canonical Questions:
  [?] Wat is cardioversie?
  [?] Hoe verloopt een cardioversie procedure?
  [?] Welke risico's zijn er bij cardioversie?

[conditions] [static] [BM25 Indexed: ✓]

Analytics Reset

The Analytics page includes two levels of data reset:

Reset All

The "Reset" button in the page header clears all accumulated statistics. This is useful for fresh demonstrations:

1. Navigate to the Analytics page
2. Click the Reset button in the header
3. Confirm the deletion in the dialog
4. All query metrics, feedback data, conversations, messages, and performance statistics are cleared

Delete Feedback Only

The FeedbackMetrics component includes a small trash icon button that deletes only feedback-related data while preserving query history and other analytics. This is useful when feedback data needs to be reset without losing the query analytics:

1. Navigate to the Analytics page
2. Locate the Feedback metrics card
3. Click the small trash icon next to the card title
4. A 2-stage confirmation appears inline: first the trash icon, then a "Delete feedback data?" prompt with confirm/cancel buttons
5. Only FeedbackEvent and CitationClickEvent records are deleted

The endpoint is DELETE /api/v1/analytics/feedback, separate from the full reset endpoint. Both the button label and confirmation text are available in English and Dutch via the i18n system (feedback.resetFeedback, feedback.deleteFeedbackData).

Operations Metrics (Costs Tab)

The Analytics page includes a costs tab (visible to the Owner role only) with two trend charts that surface system-quality signals derived from the operational tables added in migrations 066 and 067:

Chart	Component	Backend endpoint	Data source
Category Mismatch Trend	CategoryMismatchTrend.tsx (frontend/src/components/Analytics/)	GET /api/v1/admin/ops/category-mismatch (backend/app/api/admin_ops.py:342)	app.category_mismatch_telemetry (migration 066)
Diagnostic Accuracy Trend	DiagnosticAccuracyTrend.tsx	GET /api/v1/admin/ops/diagnostic-accuracy (backend/app/api/admin_ops.py:448)	app.diagnostic_feedback (migration 067)

The Category Mismatch Trend plots the per-day mean of mismatch_rate from the Value Framework's affinity-rerank telemetry — the fraction of top-K chunks whose category was OFF the intent's preferred set. A persistent rise in mismatch_rate signals retrieval-steering drift (the affinity coefficients need retuning, or the corpus has accumulated content the intent classifier doesn't model). The Diagnostic Accuracy Trend plots the per-day operator agreement rate (verdict ∈ {agree, partial, disagree}) on v2 diagnostic-investigation outputs — the calibration loop that closes feedback from operator review back to model behaviour.

See Storage Architecture §Operational & Analytics Tables for the underlying schemas.

Citation Hover Tooltips

Citation markers ([1], [2], etc.) in the streaming response display a tooltip on hover showing the source filename and URL. These tooltips use a React portal (createPortal) to render on document.body, outside all scroll containers.

This portal-based approach was adopted because the original CSS-only tooltips were clipped by overflow-hidden on ancestor containers (the chat message scroll area). By rendering the tooltip as a fixed-position element on the document body with z-index: 9999, it is always visible regardless of the scroll container hierarchy.

The tooltip automatically closes on scroll (since the anchor element moves but the portal position does not update) and positions itself relative to the citation marker's bounding rectangle, clamped to stay within the viewport.

Escalated Pipeline Stages

When "Think Harder" is triggered (user feedback or automatic escalation), additional pipeline stages become visible in the debug panel:

Stage	Badge	Color	Description
SEARCHING	Think Harder escalation	Orange border	Indicates re-search with expanded parameters
ANALYZING	Cross-encoder reranking	Purple	Reranker model re-scored top results
GENERATING	Escalation model	Gold	Higher-tier LLM model used for generation

These stages are always-on in "full mode" (see ADR-0024) — the Think Harder button is hidden and cross-encoder reranking runs on every query.

Query Rewriting Visualization

The UNDERSTANDING stage includes detailed query rewriting information:

Badge	Meaning
Original: "wat kost dat?"	The raw user query
Rewritten: "Wat kost parkeren bij ZOL?"	LLM-rewritten follow-up query
Follow-up: true	LLM detected this as a follow-up question
Strategy: hybrid	Selected retrieval strategy with confidence

When the LLM rewrite fails, the fallback path is visible as either:

• LLM rewrite — for short queries (≤4 words), a fast Tier 2 model call resolves references
• Topic enrichment — citation filenames and previous questions are prepended for better vector search

Integration with Pipeline Debug Page

For a full post-hoc analysis of any query, the Pipeline Debug page (/pipeline) provides:

• Complete stage-by-stage breakdown with timing
• Retrieved chunks with similarity scores and boost factors
• Full LLM prompt and response
• Evaluation metrics with quality gate pass/fail
• Cost tracking per stage

The real-time debug panel (described here) shows data during query execution, while the Pipeline Debug page shows the complete picture after execution completes. This separation follows Shneiderman's (2016) principle of progressive disclosure -- showing summary information in real time while making detailed analysis available on demand.

Pipeline Animation Page

The Pipeline Animation page (/pipeline-animation) provides an animated, stage-by-stage replay of query execution for academic demonstrations. See Pipeline Animation for full documentation.

References

• Shneiderman, B., Plaisant, C., Cohen, M., Jacobs, S., & Elmqvist, N. (2016). Designing the User Interface: Strategies for Effective Human-Computer Interaction (6th ed.). Pearson.