Digital Lock On

Appearance

ADR-009: Data syncronisation strategy ​

Context ​

The Digital Lock On platform requires real-time data synchronisation across all connected devices to ensure Site Protectors, RPOs, and other users have accurate, current information for safety-critical decisions. When one user performs an action (worker lock-on/off, plant status changes, protection state updates), all other connected users must receive these updates automatically without manual refresh.

Key constraints:

  • Must support offline-first workflows for worker/plant lock-on and lock-off
  • Authentication and multi-user interactions (handover, worksite activation) require online connectivity
  • Must integrate with existing 5-second heartbeat mechanism (ADR-007)
  • Solution must be simple and pragmatic for initial release

Decision ​

We will implement polling-based data synchronisation at a 5-second interval, aligned with our existing heartbeat mechanism.

Technical Approach ​

  • Polling Interval: 5 seconds (matches ADR-007 heartbeat frequency)
  • Mechanism: HTTP polling requests to check for data updates
  • Offline Behaviour: Changes queued locally and synchronised when connectivity restored
  • Online-Required Operations: Authentication, handover, worksite activation/authorisation
  • Offline-Capable Operations: Worker/plant lock-on and lock-off, site limit changes

Implementation Strategy ​

  1. Piggyback data sync checks on existing heartbeat requests where possible
  2. Queue local changes during offline periods
  3. Synchronise queued changes when connectivity restored
  4. Display appropriate loading/sync indicators in UI

Future Evolution ​

This polling approach is suitable for v1 and provides a foundation for future enhancement. When scale or real-time requirements demand it, we can migrate to Server-Sent Events (SSE) or WebSockets without changing the functional behaviour exposed to users.

Consequences ​

Positive ​

  • Simple Implementation: Straightforward HTTP polling, no complex connection management
  • Consistent Intervals: Aligns with existing heartbeat, reduces network overhead
  • Offline Support: Works naturally with offline-first workflows
  • Migration Path: Clear upgrade path to SSE/WebSockets when needed
  • Debuggable: Easy to troubleshoot and monitor

Negative ​

  • Network Overhead: More requests than push-based approaches (though minimal at 5-second intervals)
  • Latency: Up to 5-second delay for updates (acceptable for current requirements)
  • Scalability: May need optimisation as user base grows

Neutral ​

  • Battery Impact: Minimal additional drain beyond existing heartbeat
  • Server Load: Manageable with current architecture, scalable with caching strategies

Alternatives Considered ​

Server-Sent Events (SSE) ​

  • Pros: More efficient for server-to-client updates, lower latency
  • Cons: More complex implementation, requires persistent connections
  • Rejection Reason: Over-engineering for v1; polling is sufficient for current scale

WebSockets ​

  • Pros: True bidirectional real-time communication, most efficient at scale
  • Cons: Significantly more complex, requires connection state management, load balancer considerations
  • Rejection Reason: Unnecessary complexity for current requirements; viable for v2+

Longer Polling Intervals (10-30 seconds) ​

  • Pros: Lower network overhead
  • Cons: Unacceptable delay for safety-critical operations, inconsistent with heartbeat timing
  • Rejection Reason: 5-second interval provides right balance for rail safety context

Implementation Notes ​

Polling Behaviour ​

  • Poll every 5 seconds when app is active and online
  • Suspend polling when app is backgrounded (respect browser/OS lifecycle)
  • Resume polling immediately when app returns to foreground
  • Display sync status indicators to users

Error Handling ​

  • Retry failed polls with exponential backoff
  • Gracefully degrade to offline mode if repeated failures
  • Clear user feedback about connectivity status

Internal use only