Pipeline Animation Page

The Pipeline Animation page (/pipeline-animation) provides a real-time animated replay of query execution, designed for academic demonstrations. It visualises every RAG pipeline stage with timing, data flow, and LLM explanations.

Purpose

During thesis defence and live demonstrations, this page allows examiners to observe exactly how a user query flows through the system — from intent classification to final answer generation — with animated transitions between stages. The stage-by-stage replay design follows Nielsen's (1993, Usability Engineering) response-time guidelines: feedback within ~0.1 s feels instantaneous; within ~1 s preserves flow; >10 s loses attention. The per-stage transitions target the 0.1–1 s band so a viewer perceives causality between stages rather than independent flashes.

Access

Navigate to /pipeline-animation/:executionId with a valid pipeline execution ID. Execution IDs are available from the Pipeline Debug page (/pipeline) or the Analytics page.

Autoplay can be enabled via the ?autoplay=true query parameter for unattended demonstrations.

Animation Stages

The page maps raw pipeline stages into animated cards, played sequentially. The normal pipeline has 9 core stages, with Citation Building and Safety Validation stages also available:

Normal Pipeline

#	Stage	What it shows
1	Query Input	Original user query, language detection
2	Embedding Generation	Vector embedding model (text-embedding-3-large, 1,536-dim), timing
3	Intent Classification	Detected intent, confidence, retrieval strategy
3b	Query Decomposition	When triggered: sub-question count, chunks-before-merge, decomposition flag (QueryDecompositionStage.tsx)
4	Query Rewriting	Original vs. rewritten query (follow-up resolution)
5	Retrieval	Search method (hybrid/vector/BM25), documents found, top chunks with similarity scores
6	Metadata Boosting	Boost factors applied (category, recency, context), before/after ranking
7	Context Assembly	Chunk selection, token budget, context window composition
8	LLM Generation	Model used, token count, cost, streaming response
9	Quality Gate	Evaluation scores (faithfulness, relevancy), grade, pass/fail
10	Citation Building	Chunk-to-citation mapping, source document references
11	Safety Validation	Post-generation safety checks, disclaimer injection

Stage 3b (Query Decomposition) appears between Intent Classification and Query Rewriting only when query_decomposition_service.py splits a complex query into sub-questions. For the common single-hop case, the stage is skipped and the animation transitions directly from Stage 3 to Stage 4. See frontend/src/components/PipelineAnimation/stages/QueryDecompositionStage.tsx.

Escalated Pipeline (Think Harder)

When the query was escalated (via user feedback or automatic threshold), two additional stages appear:

#	Stage	What it shows
5b	Expanded Retrieval	Re-search with broader parameters, additional documents found
6b	Cross-Encoder Re-ranking	Reranker model scores, before/after ordering of chunks

These stages insert between normal Retrieval and Context Assembly.

Stage Cards

Each stage is rendered as an animated card (StageCard component) with:

• Header: Stage name, icon, duration in milliseconds
• Input/Output panels: Collapsible panels showing raw stage data, following Shneiderman et al.'s (2016) progressive disclosure principle
• Citation building: For retrieval stages, shows chunk-to-citation mapping
• LLM explanation: Optional AI-generated plain-language explanation of what happened
• Token & cost: Where applicable, shows LLM token usage and cost

Autoplay

The useAutoplay hook drives automatic progression through stages:

1. Each stage displays for a configurable duration (based on actual execution timing)
2. Transitions use Motion (AnimatePresence) for smooth slide-in/out animations
3. A progress bar shows overall animation progress
4. Autoplay can be paused/resumed via the header controls

Summary Card

After all stages complete, a SummaryCard shows:

• Total pipeline execution time
• Total LLM tokens consumed
• Total cost
• Final quality gate result (pass/fail with scores)
• Link to full Pipeline Debug view

Technical Implementation

The page is implemented in frontend/src/pages/PipelineAnimationPage.tsx with supporting components in frontend/src/components/PipelineAnimation/:

• AnimationHeader.tsx — Controls (play/pause, reset, autoplay toggle)
• StageCard.tsx — Generic animated stage wrapper
• SummaryCard.tsx — End-of-animation summary
• stages/*.tsx — Stage-specific renderers (13 total, including escalated and post-generation stages: QueryInputStage, EmbeddingGenerationStage, IntentClassificationStage, QueryDecompositionStage, QueryRewritingStage, RetrievalStage, MetadataBoostingStage, ContextAssemblyStage, LLMGenerationStage, QualityGateStage, CitationBuildingStage, SafetyValidationStage, CrossEncoderRerankingStage)
• animations/useAutoplay.ts — Autoplay timing hook

Data is fetched from the GET /api/v1/analytics/pipeline/:id endpoint via analyticsService. Autoplay can be enabled via the ?autoplay=true URL parameter (e.g., /pipeline-animation/abc-123?autoplay=true) for unattended demonstrations.

References

• Nielsen, J. (1993). Usability Engineering. Academic Press. Response time guidelines informing the per-stage timing feedback design.
• Shneiderman, B., Plaisant, C., Cohen, M., Jacobs, S., & Elmqvist, N. (2016). Designing the User Interface: Strategies for Effective Human-Computer Interaction (6th ed.). Pearson. Principles for progressive disclosure and animated transitions in complex system interfaces.