Progress Bar
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Visual feedback during long-running processes with multi-user visibility Domain: PROGRESS
Statement
The system shall display progress indicators during long-running processes, providing visual feedback with process name and percentage completion.
Progress tracking supports navigation persistence (progress continues in background when users navigate away), concurrent process display (multiple indicators simultaneously), and multi-user visibility (all users viewing an affected resource see the same progress status). Administrators can configure the duration threshold that triggers progress display and the update frequency.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Long-running process | A system operation that the system calculates will take more than the configured threshold (default 10 seconds) to complete |
| Progress indicator | A visual element displaying process name and percentage completion |
| Blocking display | A UI state where primary screen content is inaccessible while an overlay is active |
Functional Requirements
Progress Display (REQ-PROGRESS-001)
FR-PROGRESS-001 Display Progress for Long-Running Processes
The system shall display a progress indicator when a process is calculated to exceed the long-running threshold.
Acceptance Criteria:
Display Behavior:
- Display a progress indicator when the calculated process duration exceeds the configured threshold
- Display the name of the executing process
- Display the percentage complete
- Update the percentage at the configured interval
Screen Interaction:
- The primary screen content shall be inaccessible while the progress indicator is displayed
- Navigation elements shall remain accessible while the progress indicator is displayed
Configuration:
- The long-running process threshold shall be 10 seconds by default and shall be configurable
- The progress update interval shall be 2 seconds by default and shall be configurable
Error Handling
- Process fails during execution: The system shall dismiss the progress indicator and display an error notification
- Progress calculation unavailable: The system shall display an indeterminate progress indicator
Trace: Source: 3.0.0-Progress Bar (Rows 1, 2, 3, 4) | Jira: BT-2159 | Epic: BT-2330 | Tests: See scenarios
Navigation Persistence (REQ-PROGRESS-002)
FR-PROGRESS-002 Persist Progress Tracking Across Navigation
The system shall continue tracking process progress when the user navigates away from the originating screen.
Acceptance Criteria:
- The progress indicator shall be hidden when the user navigates to another screen
- The system shall continue updating progress tracking in the background
- The progress indicator shall be displayed again with current status when the user returns to the process screen
Trace: Source: 3.0.0-Progress Bar (Rows 5, 6) | Jira: BT-2159 | Epic: BT-2330 | Tests: See scenarios
Concurrent Processes (REQ-PROGRESS-003)
FR-PROGRESS-003 Support Multiple Concurrent Progress Indicators
The system shall track and display progress independently for multiple simultaneous long-running processes.
Acceptance Criteria:
- Multiple progress indicators shall be displayed simultaneously when multiple processes are running
- Each progress indicator shall display its own process name and percentage complete
- Progress updates for each process shall be independent
Trace: Source: 3.0.0-Progress Bar (Row 7) | Jira: BT-2159 | Epic: BT-2330 | Tests: See scenarios
Multi-User Visibility (REQ-PROGRESS-004)
FR-PROGRESS-004 Display Progress to All Users Viewing Affected Resources
The system shall display the progress indicator to all users viewing a resource on which a long-running process is active.
Acceptance Criteria:
- Users who open a resource while a process is in progress shall see the progress indicator
- Users who have a resource open when a process starts shall see the progress indicator appear
- The progress indicator shall show the same status to all users viewing the resource
Trace: Source: 3.0.0-Progress Bar (Row 8) | Jira: BT-2159 | Epic: BT-2330 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
long_running_threshold_seconds | 10 | Minimum calculated duration to trigger progress display | REQ-PROGRESS-001 |
progress_update_interval_seconds | 2 | Frequency of progress percentage updates | REQ-PROGRESS-001 |
Assumptions
- Users have appropriate role permissions to view affected resources
- The system can calculate expected process duration before displaying progress
- Network connectivity supports real-time progress updates across user sessions
- At least one process type supports progress tracking (e.g., Reanalysis)
- Real-time communication channel exists between server and all connected clients viewing the resource (for REQ-PROGRESS-004)
UI Notes (Illustrative)
FR-PROGRESS-001 UI Specifications
Layout:
- Progress bar displays as overlay on part of screen
- Run File screen content is blocked/inaccessible
- Sidebar navigation remains visible and functional
Display Elements:
- Process name label
- Percentage complete indicator
- Visual progress bar representation
Visual Reference:
- See:
media/image182.png
Implementation Notes:
- Use existing system UI components for consistency with application design
FR-PROGRESS-002 UI Specifications
- Progress bar is hidden when user navigates away (not destroyed)
- Progress bar reappears in same position when user returns
FR-PROGRESS-003 UI Specifications
- Multiple progress bars can display simultaneously
- Each progress bar is visually distinct with its own process identifier
FR-PROGRESS-004 UI Specifications
- Progress bar appearance is synchronized across all user sessions viewing the same resource
- No visual distinction between progress initiated by current user vs. another user
Implementation (Illustrative)
| Component | Type | Path | Requirements |
|---|---|---|---|
| RunAnalyseProgress | Support | code/app/Support/RunAnalyseProgress.php | REQ-PROGRESS-001, REQ-PROGRESS-002, REQ-PROGRESS-003, REQ-PROGRESS-004 |
| RunAnalyseProgressUpdated | Event | code/app/Events/RunAnalyseProgressUpdated.php | REQ-PROGRESS-001, REQ-PROGRESS-004 |
| RunAnalyzeStarted | Event | code/app/Events/RunAnalyzeStarted.php | REQ-PROGRESS-001, REQ-PROGRESS-004 |
| RunUpdated | Event | code/app/Events/RunUpdated.php | REQ-PROGRESS-001 |
| RunAnalyseJob | Job | code/app/Jobs/RunAnalyseJob.php | REQ-PROGRESS-001, REQ-PROGRESS-002, REQ-PROGRESS-003 |
| ProgressIndicator | Vue Component | components/runs/ProgressIndicator.vue | REQ-PROGRESS-001, REQ-PROGRESS-002, REQ-PROGRESS-003, REQ-PROGRESS-004 |
Architecture Notes:
- Progress is tracked via cache (
RunAnalyseProgress) and broadcast via Pusher (RunAnalyseProgressUpdated) - Multi-user visibility achieved through
ShouldBroadcastNowevents onRun.Analysechannel - Navigation persistence supported by cache-based tracking separate from UI state
- Concurrent processes tracked with separate cache keys per runId
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-PROGRESS-001 | Display Progress for Long-Running Processes | Test | RunAnalyseProgress, RunAnalyseProgressUpdated, RunAnalyseJob | BT-2251 | Draft |
| REQ-PROGRESS-002 | Persist Progress Tracking Across Navigation | Test | RunAnalyseProgress (cache-based), RunAnalyseJob | BT-2251 | Draft |
| REQ-PROGRESS-003 | Support Multiple Concurrent Progress Indicators | Test | RunAnalyseProgress (per-run keys), RunAnalyseJob | BT-2261 | Draft |
| REQ-PROGRESS-004 | Display Progress to All Users Viewing Affected Resources | Test | RunAnalyseProgressUpdated (ShouldBroadcastNow), Pusher channel | BT-2261 | Draft |
Notes
- Progress tracking is primarily used for Reanalysis operations on Run Files
- The blocking behavior prevents user actions that could conflict with the in-progress operation
- Real-time updates rely on server-push communication for multi-user synchronization
Acceptance Tests
Test: REQ-PROGRESS-001
Test: Progress bar trigger
Given: User initiates a process that will take more than 10 seconds
When: The system calculates the expected duration
Then: A progress indicator is displayed
Test: Progress bar content
Given: A long-running process is active
When: The progress indicator is displayed
Then: The name of the process is shown
And: The percentage complete is shown
Test: Progress bar update frequency
Given: A long-running process is active with progress indicator displayed
When: 2 seconds elapse
Then: The percentage complete is updated
Test: Screen blocking
Given: A long-running process is active on the Run File screen
When: The progress indicator is displayed
Then: The Run File screen is inaccessible
And: The sidebar navigation remains accessible
Test: Error during process
Given: A long-running process is active with progress indicator displayed
When: The process fails during execution
Then: The progress indicator is dismissed
And: An error notification is displayed
Test: Indeterminate progress
Given: User initiates a process
When: Progress calculation is unavailable
Then: An indeterminate progress indicator is displayed
Test: REQ-PROGRESS-002
Test: Navigate away
Given: A long-running process is active with progress indicator displayed
When: User navigates to another screen via sidebar
Then: The progress indicator is no longer visible
And: The process continues running in the background
Test: Navigate back
Given: A long-running process is active
And: User has navigated away from the process screen
When: User navigates back to the screen running the process
Then: The progress indicator is displayed again
And: The progress indicator shows the current percentage complete
Test: REQ-PROGRESS-003
Test: Multiple simultaneous processes
Given: User initiates Process A (long-running)
And: Progress indicator for Process A is displayed
When: User initiates Process B (long-running)
Then: Progress indicators for both Process A and Process B are displayed
And: Each shows its own name and percentage complete
Test: REQ-PROGRESS-004
Test: User opens file during reanalysis
Given: User A initiates Reanalysis on Run File X
And: Reanalysis is in progress
When: User B opens Run File X
Then: User B sees the progress indicator for the Reanalysis
Test: User has file open when reanalysis starts
Given: User B has Run File X open
When: User A initiates Reanalysis on Run File X
Then: User B sees the progress indicator appear for the Reanalysis
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- AC do not introduce new capabilities
- Traceability matrix is complete
Reviewer Notes
No Consolidation Required
The four requirements in this domain represent distinct, non-overlapping capabilities:
| Requirement | Capability | Assessment |
|---|---|---|
| REQ-PROGRESS-001 | Core progress display | Fundamental capability |
| REQ-PROGRESS-002 | Navigation persistence | Distinct state management |
| REQ-PROGRESS-003 | Concurrent processes | Distinct multi-process handling |
| REQ-PROGRESS-004 | Multi-user visibility | Distinct session synchronization |
Rationale: These requirements do not exhibit the "requirement explosion" pattern. Each describes a genuinely different system behavior that cannot be meaningfully combined without losing testability or clarity.
Reversibility: Source file preserved at output/srs/progress.md