Global UI
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Cross-cutting user interface features across the application Domain: GLOBALUI
Statement
The system shall provide consistent cross-cutting user interface behaviors that apply throughout the application, including system status communication, session management, user identification, notification delivery, and user preference controls.
These requirements address global concerns that transcend individual feature domains, ensuring consistent behavior for maintenance mode display, session lifecycle handling with termination messaging, user identity presentation via display names and role indicators, site filtering based on Cognito group membership, and system-wide preference management such as infinite scrolling.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Maintenance Mode | A system state during deployment where normal application access is suspended and users see a status page |
| Session Timeout | Automatic termination of a user session after the configured maximum session duration elapses |
| Idle Timeout | Automatic termination of a user session after the configured period of user inactivity |
| Cognito User Group | An AWS Cognito attribute that indicates the user's group membership for site access filtering |
| Display Name | The user's human-readable name used for identification throughout the application, distinct from the technical username |
| Infinite Scrolling | A pagination behavior where additional content loads automatically as the user scrolls, rather than requiring explicit page navigation |
Functional Requirements
System Status Communication (REQ-GLOBALUI-001, REQ-GLOBALUI-002)
FR-GLOBALUI-001 Display Maintenance Status
The system shall display a maintenance status page to users attempting to access the application during system deployment or maintenance operations.
Acceptance Criteria:
Access Control:
- During deployment, all access attempts shall be redirected to the maintenance status page
User Communication:
- The maintenance status page shall communicate that the system is temporarily unavailable
- The maintenance status page shall replace error pages during deployment
Trace: Source: 3.0.0-Maintenance mode (Row 1, 2) | Jira: BT-744 | Epic: BT-662 | Tests: See scenarios
FR-GLOBALUI-002 Display Application Version
The system shall display the deployed application version number to authorized users.
Acceptance Criteria:
Access Control:
- The version number shall be visible only to users with Super Admin role
Display Behavior:
- The version number shall be displayed in all deployment environment types
Assumptions:
- Super Admin role is the only role authorized to view version information
Trace: Source: 3.0.0-Version number displayed (Row 1, 2, 3) | Jira: BT-210 | Tests: See scenarios
Session Management (REQ-GLOBALUI-003, REQ-GLOBALUI-004)
FR-GLOBALUI-003 Communicate Session Termination Reason
The system shall display an explanatory message when a user's session is terminated, indicating the reason for termination and prompting re-authentication.
Acceptance Criteria:
Termination Messages:
- Session timeout shall trigger a message explaining session expiration
- Inactivity timeout shall trigger a message explaining inactivity termination
User Redirection:
- The user shall be redirected to the authentication interface after termination
- The termination reason message shall be displayed on the authentication interface
Trace: Source: 3.0.0-Change Session Management Experience (Row 1, 2) | Jira: BT-3213 | Epic: BT-3212 | Tests: See scenarios
FR-GLOBALUI-004 Provide Idle Timeout Warning
The system shall warn users before automatic logout due to inactivity, providing an opportunity to cancel the logout by interacting with the application.
Acceptance Criteria:
Warning Display:
- When the user is inactive for the configured idle time, a warning shall be displayed
- The warning shall include a visible countdown indicating time remaining before logout
Countdown Behavior:
- If the countdown reaches zero, the user shall be automatically logged out
- If the user interacts with the application before countdown ends, the warning shall be dismissed
- Dismissing the warning via interaction shall reset the idle timeout timer
Trace: Source: 3.0.0-Alert for Idle Timeout Logout (Row 1) | Jira: BT-5721 | Epic: BT-5719 | Tests: See scenarios
Notification Management (REQ-GLOBALUI-005)
FR-GLOBALUI-005 Paginate Application Notifications
The system shall load notifications incrementally using pagination to optimize user experience and system performance.
Acceptance Criteria:
Initial Load:
- Initial notification load shall be limited to the configured initial count
- Notifications shall be available for the configured retention period
Pagination Controls:
- When no more notifications exist, the system shall indicate end of available notifications
- When additional notifications exist, the system shall provide an option to load more
- User shall be able to select the quantity of additional notifications to load
- Loading additional notifications shall append them to the existing list
Trace: Source: 3.0.0-Paginate App Notifications (Row 1, 2, 3, 4, 5) | Jira: BT-3445 | Epic: BT-3322 | Tests: See scenarios
User Identification (REQ-GLOBALUI-006, REQ-GLOBALUI-007, REQ-GLOBALUI-008)
FR-GLOBALUI-006 Display User Display Names
The system shall display user display names instead of usernames throughout the application for user identification.
Acceptance Criteria:
Display Locations:
- User identification in report screens shall show display names (except Audit Report)
- User identification in exported files shall show display names
- User identification in the application header shall show display names
Exception:
- Audit Report shall display usernames (not display names) for compliance and audit trail purposes
Trace: Source: 3.0.0-Application - Show 'Display Name' instead of 'Username' (Row 1, 2, 3) | Jira: BT-3852 | Tests: See scenarios
FR-GLOBALUI-007 Filter Sites by Cognito Group
The system shall filter available sites based on the user's Cognito group membership and each site's Cognito group requirement configuration.
Acceptance Criteria:
Filtering Logic:
- Users with a Cognito User Group shall see all sites regardless of site configuration
- Users without a Cognito User Group shall only see sites that do not require Cognito group membership
- Sites configured to require Cognito group shall be hidden from users without Cognito group membership
Truth Table:
| User Has Cognito Group | Site Requires Cognito Group | Site Visible |
|---|---|---|
| Yes | Yes | Yes |
| Yes | No | Yes |
| No | Yes | No |
| No | No | Yes |
Trace: Source: 3.0.0-Application - Site Picker (Row 1, Truth Table) | Jira: BT-3785 | Epic: BT-3780 | Tests: See scenarios
FR-GLOBALUI-008 Display User Role Indicator
The system shall display a visual indicator of the user's role alongside their identity information.
Acceptance Criteria:
Display Requirements:
- Each user role shall have a distinct visual indicator
- The role indicator shall be displayed adjacent to the user's display name
Interaction:
- Extended role information shall be available on user interaction with the indicator
Trace: Source: 3.0.0-Show users role indicator in navigation bar with the tooltip (Row 1) | Jira: BT-4044 | Epic: BT-4030 | Tests: See scenarios
User Preferences (REQ-GLOBALUI-009)
FR-GLOBALUI-009 Provide Infinite Scrolling Toggle
The system shall allow users to enable or disable infinite scrolling behavior system-wide.
Acceptance Criteria:
Toggle Control:
- Users shall be able to toggle infinite scrolling on or off
- The toggle control shall reflect the current state of infinite scrolling
System-Wide Effect:
- Toggling shall change infinite scrolling behavior across all applicable screens
- The toggle state shall persist across user sessions
Trace: Source: 3.0.0-Add 'Infinite Scrolling Toggle' (Row 1) | Jira: BT-5555 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
notification_initial_load | 10 | Number of notifications loaded on initial display | REQ-GLOBALUI-005 |
notification_retention_days | 30 | Number of days notifications are retained and available | REQ-GLOBALUI-005 |
notification_load_more_options | 10, 20, 30, 50 | Available options for loading additional notifications | REQ-GLOBALUI-005 |
session_timeout_duration | Configurable | Maximum session duration before automatic termination | REQ-GLOBALUI-003 |
idle_timeout_duration | Configurable | Inactivity duration before idle timeout warning | REQ-GLOBALUI-004 |
idle_warning_countdown | Configurable | Duration of countdown timer in idle timeout warning | REQ-GLOBALUI-004 |
default_infinite_scrolling | true | Default state for infinite scrolling preference | REQ-GLOBALUI-009 |
Assumptions
- Users accessing the application have valid authentication credentials
- Session and idle timeout durations are configured by system administrators
- Site configurations include Cognito group requirements where applicable
- All user accounts have both username and display name attributes defined
- Network connectivity is available for session management operations
UI Notes (Illustrative)
FR-GLOBALUI-001 UI Specifications
- Dedicated maintenance page displayed instead of error pages during deployment
- Default message text: "The system is currently down for essential maintenance. We will be back up as soon as we can - please check back later."
- Simple, clear messaging design to reduce user confusion
FR-GLOBALUI-002 UI Specifications
- Version number displayed at the bottom of the sidebar
- Only visible to super-admin users
FR-GLOBALUI-003 UI Specifications
- Session timeout message example: "Your session has been terminated for security reasons (timeout). Please login again"
- Inactivity timeout message example: "Your session has been terminated due to inactivity. Please login again"
- Message displayed on the login form after redirect
FR-GLOBALUI-004 UI Specifications
- Alert displayed with visible countdown timer
- Alert dismissible via any user interaction with the application
FR-GLOBALUI-005 UI Specifications
- End-of-list message: "That's all your notifications from the last 30 days."
- "See More..." link with dropdown options (10, 20, 30, 50)
- Clear visual separation between notifications and pagination controls
FR-GLOBALUI-008 UI Specifications
- Role indicator displayed inside a colored circle in front of user display name
- Tooltip shows full role name on hover
Role-specific visual design:
| Role | Indicator | Circle Color | Tooltip |
|---|---|---|---|
| Senior User | S | #49D1A0 (green) | Senior user |
| Junior User | J | #B7B0FF (purple) | Junior user |
| Super Admin | SA | #000000 (black) | Super Admin user |
| Client Admin | CA | #FAA07A (orange) | Client Admin user |
| Manager | M | #FF3A8D (pink) | Manager user |
FR-GLOBALUI-009 UI Specifications
- Toggle button displayed in the application top bar
- Toggle visually reflects enabled/disabled state
Implementation (Illustrative)
This domain is primarily frontend-implemented in Vue.js components. The backend provides:
| Component | Type | Path | Requirements |
|---|---|---|---|
| SpaController | Controller | Backend | REQ-GLOBALUI-002 to 009 |
| MaintenanceViewController | Controller | Backend | REQ-GLOBALUI-001 |
| FeaturesController | Controller | Backend | REQ-GLOBALUI-009 |
| Feature | Model | Backend | REQ-GLOBALUI-009 |
| GetFeaturesAction | Action | Backend | REQ-GLOBALUI-009 |
| ToggleFeatureAction | Action | Backend | REQ-GLOBALUI-009 |
| GetFeatureListAction | Action | Backend | REQ-GLOBALUI-009 |
Architecture Notes:
- Most Global UI requirements are implemented in Vue.js frontend components
- REQ-GLOBALUI-001 (Maintenance Mode) uses Laravel's maintenance mode framework via
MaintenanceViewController - REQ-GLOBALUI-009 (Infinite Scrolling Toggle) is implemented as a feature flag managed through the Features subsystem
- Session management (REQ-GLOBALUI-003, 004) uses Laravel session with Cognito authentication (see
sdd-security.md) - Site filtering (REQ-GLOBALUI-007) logic resides in site query builders (see
output/srs/site.md)
Frontend Components:
| Component Type | Location |
|---|---|
| View | views/Settings.vue |
| Components | components/app-notifications/ |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-GLOBALUI-001 | Display Maintenance Status | Test | MaintenanceViewController | [Pending] | Draft |
| REQ-GLOBALUI-002 | Display Application Version | Test | SpaController (frontend) | BT-713 | Draft |
| REQ-GLOBALUI-003 | Communicate Session Termination Reason | Test | SpaController (frontend) | BT-925 | Draft |
| REQ-GLOBALUI-004 | Provide Idle Timeout Warning | Test | SpaController (frontend) | [Pending] | Draft |
| REQ-GLOBALUI-005 | Paginate Application Notifications | Test | SpaController (frontend) | BT-3847 | Draft |
| REQ-GLOBALUI-006 | Display User Display Names | Test | SpaController (frontend) | BT-3856 | Draft |
| REQ-GLOBALUI-007 | Filter Sites by Cognito Group | Test | SpaController (frontend), Site QueryBuilders | BT-3841 | Draft |
| REQ-GLOBALUI-008 | Display User Role Indicator | Test | SpaController (frontend) | BT-4206 | Draft |
| REQ-GLOBALUI-009 | Provide Infinite Scrolling Toggle | Test | FeaturesController, Feature, ToggleFeatureAction | BT-4773 | Draft |
Notes
- REQ-GLOBALUI-001: Laravel maintenance mode framework is used (see Laravel 8.x upgrade guide)
- REQ-GLOBALUI-007: Truth table for Cognito group filtering is documented in source for comprehensive test coverage
Open Questions
| ID | Question | Source | Owner | Date Raised |
|---|---|---|---|---|
| - | No open questions identified | - | - | - |
Acceptance Tests
Test: REQ-GLOBALUI-001
Test: Maintenance screen display
Given: The system is undergoing deployment
When: A user accesses the application URL
Then: The maintenance status page shall be displayed
And: The page shall communicate that the system is temporarily unavailable
Test: REQ-GLOBALUI-002
Test: Version visibility for super-admin
Given: User is logged in with Super Admin role
When: User views any page
Then: The version number shall be displayed
Test: Version hidden for other roles
Given: User is logged in with any role other than Super Admin
When: User views any page
Then: The version number shall NOT be displayed
Test: REQ-GLOBALUI-003
Test: Session timeout message
Given: Session timeout is configured to 1 hour
And: Idle timeout is configured to 2 hours
When: User logs in and remains active for 1 hour
Then: User shall be logged out
And: User shall be redirected to authentication interface
And: A message explaining session expiration shall be displayed
Test: Inactivity timeout message
Given: Session timeout is configured to 1 hour
And: Idle timeout is configured to 30 minutes
When: User logs in and remains inactive for 30 minutes
Then: User shall be logged out
And: User shall be redirected to authentication interface
And: A message explaining inactivity termination shall be displayed
Test: REQ-GLOBALUI-004
Test: Idle timeout warning display
Given: The application is running
When: User is inactive for the configured idle time
Then: A warning shall be displayed with a countdown
Test: Countdown expiration
Given: Idle timeout warning is displayed with countdown
When: Countdown reaches zero
Then: The system shall log out the user
Test: User cancels timeout
Given: Idle timeout warning is displayed with countdown
When: User interacts with the application before countdown ends
Then: Warning shall be dismissed
And: The system shall not log out the user
And: Idle timeout timer shall restart
Test: REQ-GLOBALUI-005
Test: Default notification load
Given: 11 notifications exist
When: User accesses the notifications
Then: Only 10 notifications shall be displayed initially
Test: End of notifications indication
Given: 1 notification exists
When: User accesses the notifications
Then: End of available notifications shall be indicated
Test: Load more option availability
Given: 11 notifications exist
When: User accesses the notifications
Then: An option to load more notifications shall be available
Test: Load additional notifications
Given: 21 notifications exist
And: 10 notifications are currently displayed
When: User requests 10 additional notifications
Then: 20 notifications shall be displayed
Test: REQ-GLOBALUI-006
Test: Display name in reports
Given: Any report screen (except Audit Report)
When: User identification is displayed
Then: The user's display name shall be shown (not username)
Test: Display name in exports
Given: Any exported file from the application
When: User identification is included
Then: The user's display name shall be shown
Test: Display name in header
Given: User is logged into the application
When: User identification is shown in the header
Then: The user's display name shall be displayed
Test: REQ-GLOBALUI-007
Test: Cognito group user sees all sites
Given: User has Cognito User Group configured
And: Site A requires Cognito group (Yes)
And: Site B requires Cognito group (No)
When: User views available sites
Then: Both Site A and Site B shall be visible
Test: Non-Cognito user site filtering
Given: User does NOT have Cognito User Group configured
And: Site A requires Cognito group (Yes)
And: Site B requires Cognito group (No)
When: User views available sites
Then: Only Site B shall be visible
And: Site A shall NOT be visible
Test: REQ-GLOBALUI-008
Test: Super admin indicator
Given: User with Super Admin role
When: User identity is displayed in navigation
Then: Super Admin role indicator shall be displayed
And: Extended role information shall be available on interaction
Test: Junior user indicator
Given: User with Junior User role
When: User identity is displayed in navigation
Then: Junior User role indicator shall be displayed
And: Extended role information shall be available on interaction
Test: Senior user indicator
Given: User with Senior User role
When: User identity is displayed in navigation
Then: Senior User role indicator shall be displayed
And: Extended role information shall be available on interaction
Test: Client admin indicator
Given: User with Client Admin role
When: User identity is displayed in navigation
Then: Client Admin role indicator shall be displayed
And: Extended role information shall be available on interaction
Test: Manager indicator
Given: User with Manager role
When: User identity is displayed in navigation
Then: Manager role indicator shall be displayed
And: Extended role information shall be available on interaction
Test: REQ-GLOBALUI-009
Test: Toggle state reflection
Given: Infinite scrolling system state is enabled
Then: The toggle control shall reflect the enabled state
Test: Toggle functionality
Given: Infinite scrolling is enabled
When: User toggles the control
Then: System-wide infinite scrolling shall be disabled
And: The toggle control shall reflect the disabled state
Test: Toggle persistence
Given: User sets infinite scrolling to disabled
When: User logs out and logs back in
Then: Infinite scrolling shall remain disabled
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Security | Cognito group-based site filtering for access control |
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
- Refinements do not introduce new capabilities
- Traceability matrix is complete
Reviewer Notes
This domain contained 9 distinct requirements representing separate cross-cutting concerns. No consolidation was performed as each requirement addresses a unique capability:
| Requirement | Capability | Disposition |
|---|---|---|
| REQ-GLOBALUI-001 | Maintenance mode display | Preserved as FR-GLOBALUI-001 |
| REQ-GLOBALUI-002 | Version number display | Preserved as FR-GLOBALUI-002 |
| REQ-GLOBALUI-003 | Session termination messages | Preserved as FR-GLOBALUI-003 |
| REQ-GLOBALUI-004 | Idle timeout warning | Preserved as FR-GLOBALUI-004 |
| REQ-GLOBALUI-005 | Notification pagination | Preserved as FR-GLOBALUI-005 |
| REQ-GLOBALUI-006 | Display name usage | Preserved as FR-GLOBALUI-006 |
| REQ-GLOBALUI-007 | Site picker filtering | Preserved as FR-GLOBALUI-007 |
| REQ-GLOBALUI-008 | Role indicator display | Preserved as FR-GLOBALUI-008 |
| REQ-GLOBALUI-009 | Infinite scrolling toggle | Preserved as FR-GLOBALUI-009 |
Rationale: Each requirement represents an independent system capability rather than variants of a single function. No requirement explosion pattern was detected.
Transformations Applied:
-
UI-centric ACs transformed to behavior-centric:
- "Toggle button is displayed in the application top bar" -> "Users shall be able to toggle infinite scrolling on or off"
- "A toggle button is displayed" -> "The toggle control shall reflect the current state"
- "Hovering over the indicator displays a tooltip" -> "Extended role information shall be available on user interaction"
-
Configuration values extracted:
- Default notification load count (10) moved to Configuration Options
- Notification retention period (30 days) moved to Configuration Options
- Load more options (10, 20, 30, 50) moved to Configuration Options
-
UI detail extracted:
- Specific message text moved to UI Notes section
- Color codes and visual design for role indicators moved to UI Notes section
- Sidebar positioning for version number moved to UI Notes section
Reversibility: Source file preserved at output/srs/globalui.md