PWA Installation and Update Management
Context & Background
The Digital Lock On system is deployed as a Progressive Web App (PWA) to provide native app-like functionality across devices whilst maintaining web-based deployment benefits. Users need to be kept on current versions to ensure security, feature availability, and compatibility with backend services, whilst avoiding workflow disruption during safety-critical operations.
This requirement covers both the initial PWA installation prompts (encouraging users to add the app to their device home screen) and the ongoing update management process that ensures users receive new versions without losing unsynchronised work or interrupting active operations.
Related Decisions
Architecture Decisions
- [ ] ADR needed: Service worker update strategy and caching approach
- [ ] ADR needed: Version compatibility matrix and support lifecycle
Pending Decisions
- [ ] Pending: Update check frequency
- [ ] Pending: Strategy for tracking update success rates and versions
User Story
As a user of the Digital Lock On platform
I want to be prompted to install the PWA to my home screen, and notified when updates are available
So that I can access the latest features and security improvements without workflow disruption or data loss, and benefit from faster access and offline capabilities.
Business Rules
- The system SHALL check for updates on every app launch.
- The system SHALL receive and process server-pushed update notifications when available.
- Update downloads SHALL occur automatically in the background without user intervention.
- Update installation SHALL NOT interrupt active user workflows or safety-critical operations.
- The system SHALL support the current version plus the previous 2-3 versions under normal circumstances.
- Critical security or safety updates SHALL be treated with higher urgency but SHALL NOT force immediate installation.
- Users SHALL be warned about unsynchronised data before update installation.
- The system SHALL prompt users to install the PWA to their device home screen.
- Update notifications SHALL be suppressed whilst the user is offline and displayed when connectivity returns.
Acceptance Criteria
Event-Driven Requirements
When the app launches, the system SHALL check for available updates.
When a server-pushed update notification is received, the system SHALL process the notification and determine update availability.
When an update is available and the user is not in the middle of an action, the system SHALL display an update notification stating that a new app version is available, and to refresh or relaunch the app.
When an update notification is displayed for a standard (non-critical) update, the system SHALL provide "Update Now", and "Remind me later" options.
When an update notification is displayed for a critical update, the system SHALL provide "Update Now" option only (no dismiss option).
When a user selects "Update Now", the system SHALL check for connectivity or unsynchronised data before proceeding.
When unsynchronised data is detected during update installation, the system SHALL display a warning such as: "You have unsynchronised changes. Updating now may result in data loss. Please wait for connectivity to complete or proceed at your own risk."
When a user confirms update installation with no unsynchronised data, the system SHALL refresh the app (or prompt to relaunch if installed to home screen).
When a user selects "Remind me later", the system SHALL suppress the update notification and display it again on the next app launch or navigation between main screens.
When an update is available and the user is offline, the system SHALL queue the notification and display it when connectivity is restored.
When a user attempts to perform an action whilst running an unsupported version, the system SHALL block the action and display a mandatory update notification: "Please update now to continue."
When a mandatory update notification is displayed, the system SHALL provide only an "Update Now" option with no dismiss or delay functionality.
When a user has not installed the PWA to their home screen and meets trigger criteria, the system SHALL display a prompt encouraging home screen installation.
State-Driven Requirements
While the user is in the middle of an action (e.g., locking workers on/off, managing plant, protection management), the system SHALL suppress update notifications.
While the user's app version is within the supported version range, the system SHALL allow normal operation without forced updates.
While the user's app version is outside the supported version range, the system SHALL restrict functionality and require update installation.
While the device is offline, the system SHALL queue any update notifications received from the server.
Ubiquitous Requirements
The system SHALL download updates automatically in the background without user intervention.
The system SHALL preserve user session state and authentication across app updates where possible.
The system SHALL log all update checks, installations, and user responses for troubleshooting and analytics.
The system SHALL support both browser-based and home screen-installed PWA deployment models.
Conditional Requirements
Where the user has dismissed an update notification, the system MAY display the notification again when navigating between main screens.
Where multiple updates are available, the system SHALL download and install them cumulatively, moving the user to the latest version in a single update action.
Unwanted Behaviour
If an update is available but the user has unsynchronised data, then the system SHALL NOT proceed with update installation without explicit user acknowledgment of potential data loss.
If the user is performing a safety-critical operation (e.g., protection management, worker lock-on/off), then the system SHALL NOT display update notifications until the operation is complete.
If the device is offline when an update notification should be displayed, then the system SHALL NOT lose the notification but queue it for display when connectivity returns.
Dependencies
Requires:
- REQ-CONN-001: Real-Time Data Synchronisation - To detect unsynchronised data before updates
- Service worker implementation for background updates and offline support
- Version metadata endpoint to determine update availability
- Server-push notification infrastructure for update alerts
Enables:
- Consistent user experience across all devices
- Rapid deployment of security patches and new features
- Improved offline functionality through home screen installation
Linked Specifications
- [ ] To be specified: Service worker update lifecycle and caching strategy
- [ ] To be specified: Version compatibility matrix and deprecation timeline
- [ ] To be specified: PWA installation prompt UI components
- [ ] To be specified: Update UI components and user flow
- [ ] To be specified: Update check API endpoints and server-push mechanism
Notes
- The term "PWA" in this document refers to Progressive Web App, distinct from "PWA" meaning Protected Work Area used elsewhere in the system
- Update timing should prioritise user experience over immediate deployment, except for critical security/safety updates
- Version support lifecycle (current + 2-3 previous versions) should be documented separately and communicated to users through release notes