Task Progress Indicator Implementation

Date: March 17, 2026

Overview

Implemented a comprehensive task progress indicator system that shows pending AI/OCR tasks at both examination and document levels. The indicator only appears when there are pending tasks, providing users with a clear overview of processing status.

Components Created

1. TaskProgressIndicator Component

File: frontend/src/components/ui/TaskProgressIndicator.tsx

Features:

Shows examination extraction status and progress
Shows document OCR processing status
Compact mode for lists, full mode for details
Auto-hides when no pending tasks
Animated indicators (pulse, spin)

Props:

examinationStatus: Current extraction status (e.g., "processing", "analyzing_text")
examinationProgress: Progress percentage (0-100)
documents: Array of documents to check OCR status
compact: Boolean for compact/list view mode

Integration Points

1. ExaminationList Page (`/examinations`)

File: frontend/src/pages/Examinations/ExaminationList.tsx

Locations:

Timeline cards - Compact mode for each examination
Preview panel - Full mode for selected examination details

Timeline Card Display: Compact mode showing:

Blue badge: "Extracting (XX%)" with Activity icon (when extraction pending)

Preview Panel Display: Full mode showing:

Examination extraction progress bar
Document OCR progress (documents are loaded for selected exam)
Detailed status labels

Code (Preview Panel):

{selectedExam && (
  <div className="mb-6">
    <TaskProgressIndicator 
      examinationStatus={selectedExam.extraction_status}
      examinationProgress={selectedExam.extraction_progress}
      documents={examDocuments}
    />
  </div>
)}

Note: Documents are loaded for the selected examination via getExaminationDocuments(selectedExam.id), so the preview panel can show both examination and document status.

2. ExaminationDetail Page

File: frontend/src/pages/Examinations/ExaminationDetail.tsx

Locations:

Header section - Full progress indicator after action buttons
Documents table - Per-document OCR status with "OCR pending" label

Display:

Full progress bar for examination extraction
Progress bar for document OCR completion
Animated pulse effects
Detailed status labels

Code:

<div className="mb-8">
  <TaskProgressIndicator 
    examinationStatus={examination?.extraction_status}
    examinationProgress={examination?.extraction_progress}
    documents={documents}
  />
</div>

Visual Design

Compact Mode (ExaminationList)

[📊 Activity] Extracting (45%) [📄 FileText] 2/5 OCR

Blue badge for extraction with pulse animation
Indigo badge for OCR with count display
Small icons, minimal spacing

Full Mode (ExaminationDetail)

┌────────────────────────────────────────────┐
│ [📊] Processing Tasks              [🕐]   │
│ AI pipeline is running                     │
│                                            │
│ analyzing_text                    45%      │
│ ████████████──────────────────────          │
│                                            │
│ Document Processing               2/5      │
│ ████████──────────────────────────          │
│ 3 pending [⚠️]                             │
└────────────────────────────────────────────┘

Blue container with border
Two progress bars (extraction + OCR)
Animated icons
Detailed labels and percentages

Status Tracking

Examination Level

Field: extraction_status (string)
Progress: extraction_progress (integer 0-100)
States: processing, aggregating, analyzing_text, defining_ontology, persisting_results, completed, failed

Document Level

Field: status (string)
States: uploaded, processing, completed, failed
Tracking: Counts pending vs completed documents

Behavior

Auto-Hide

Component renders null when:

No examination extraction pending
No document OCR pending
All tasks completed/failed

Live Updates

ExaminationDetail polls every 3 seconds during processing
Progress bars animate smoothly
Status badges pulse when active

Stall Detection

Existing stall detection (5 minutes) in ExaminationDetail
Warning prompt to restart analysis
Amber warning banner

User Experience

Benefits

Visibility: Users immediately see what's processing
Progress: Clear percentage and progress bars
Context: Shows both exam + document status together
Action: Prompts to restart stalled processes
Clean: Auto-hides when complete

Design Alignment

Matches "Run AI Analysis" button styling
Uses same color palette (blue, indigo)
Consistent animation (pulse, spin)
Rounded borders, shadow effects

Testing

Manual Testing Steps

Upload document → See OCR pending indicator
Run AI analysis → See extraction progress bar
Wait for completion → Indicator auto-hides
Check ExaminationList → Compact badges appear
Check ExaminationDetail → Full progress view

Files Modified

Created

frontend/src/components/ui/TaskProgressIndicator.tsx

Updated

frontend/src/pages/Examinations/ExaminationList.tsx
- Added import
- Added component in timeline cards
frontend/src/pages/Examinations/ExaminationDetail.tsx
- Added import
- Added component in header
- Enhanced document table status column
- Cleaned unused imports (Tag, Users)

Backend Dependencies

Examination Model

extraction_status = Column(String(50), nullable=True)
extraction_progress = Column(Integer, default=0)

Document Model

status = Column(String, default="uploaded")

Next Steps

Potential Enhancements

Tooltip Details: Hover tooltips explaining each status
Estimated Time: Show ETA for completion
Task Queue: Show number of tasks in queue
Notifications: Push notification when complete
Retry Button: Quick retry from progress indicator

Performance

Current polling: 3 seconds
Consider WebSocket for real-time updates
Batch status checks for multiple exams

Conclusion

The Task Progress Indicator provides users with clear, actionable visibility into AI/OCR processing tasks. It appears only when needed, uses consistent design patterns, and integrates seamlessly into both examination list and detail views.

Task Progress Indicator