[Quest/Malawi Core] Technical Proposal: Performance improvements for large facilities

[calmwalija]

Technical Proposal: Performance improvements for large facilities

1. Introduction

This proposal outlines the necessary refactors and new features to optimize the Tingathe application for a high-resource facility. The current implementation, which syncs all data, is causing performance issues due to the large volume of resources. We propose a more targeted approach to data synchronization and several new features to improve the application's performance and usability.

2. Proposed Changes

2.1 Custom Sync Strategy

Objective

Implement a custom sync strategy that only synchronizes patients with appointments within a specific time period (e.g., one week).

Implementation Details

• Modify the sync algorithm to query appointments for the specified time period.
• Retrieve patient resources only for patients with appointments in this period.
• Implement a configurable time window for syncing (default: 1 week).

Considerations

• Ensure that all related resources (e.g., encounters, observations) for these patients are also synced.
• Implement a mechanism to handle appointments that are rescheduled outside the sync window.

2.2 Custom Configurations for List Pages

Objective

Optimize pages that fetch and display lists of data, such as appointment lists and tracing lists.

Implementation Details

• Implement server-side pagination for large data sets.
• Use lazy loading techniques to fetch data as the user scrolls.
• Implement caching mechanisms for frequently accessed data.

Considerations

• Balance between offline availability and app performance.
• Ensure a smooth user experience when transitioning between online and offline modes.

2.3 Update Patient Picker

Objective

Modify the patient picker to fetch data directly from the server instead of relying on locally synced data.

Implementation Details

• Implement a server-side search API for patient data.
• Update the patient picker UI to use this new API.
• Implement proper error handling and loading states.

Considerations

• Ensure the feature works in offline mode, possibly with a reduced set of patients.
• Optimize the search algorithm for quick responses.

2.4 On-Demand Patient Fetching

Objective

Add functionality to fetch patient data on demand.

Implementation Details

• Option 1: Add a network section to the existing search functionality.

  • Modify the search UI to include a "Search Online" option.
  • Implement the online search functionality using the FHIR search API.

• Option 2: Create a separate UI for syncing patients.

  • Design and implement a new screen for patient syncing.
  • Allow users to search and select patients to sync.
  • Implement a background sync process for selected patients.

Considerations

• Decide which option better fits the application's UX design.
• Ensure proper handling of network errors and offline scenarios.

2.5 Bulk Patient Sync

Objective

Implement a feature to sync multiple patients at once.

Implementation Details

• Create a UI for selecting multiple patients or defining criteria for bulk sync.
• Implement a background service to handle bulk sync operations.
• Provide progress indicators and cancel options for long-running sync operations.

Considerations

• Manage device storage and performance during bulk sync operations.
• Implement retry mechanisms for failed sync attempts.

2.6 Configurable Feature Deployment

Objective

Update app configurations to allow features to be enabled or disabled based on facility requirements, ensuring the app remains fully functional in offline mode for other facilities.

Implementation Details

• Update the app configuration data.
• Implement a mechanism to fetch and apply facility-specific configurations.
• Modify each new feature to check its corresponding feature flag before activation.

Considerations

• Ensure smooth degradation of features when moving from online to offline mode.
• Implement a default configuration that maintains current functionality for non-specified facilities.

3. Technical Implementation

3.1 Custom Server-Side APIs

To optimize the sync process and reduce the load on the client side, we will implement new custom server-side APIs:

1. Sync Resources API

   • Endpoint: /api/sync/resources
   • Purpose: Retrieve all necessary resources for syncing based on appointment dates
   • Implementation:
     • Accept a date range parameter
     • Query appointments within the date range
     • Collect patient references from these appointments
     • Gather all related resources for these patients (e.g., encounters, observations)
     • Return a bundled response with all required resources

2. Flattened Tracing List API

   • Endpoint: /api/tracing/flattened-list
   • Purpose: Provide a pre-processed, flattened version of the tracing list
   • Implementation:
     • Aggregate data from multiple resources on the server
     • Return a simplified, denormalized dataset ready for display
     • Include pagination parameters for efficient data loading

3.2 Configuration System

1. Update the configurations to enable and disable this proposal

   • Since these configurations will be per facility we can add a new section to the app configs for enabling the features according to the facility. We can check the current logged-in CHW facility and enable the required feature

2. Update the configuration class in the application to accommodate the new configuration format.

   • Add sensible default (default should be off)

3. Make sure the new configuration guards all the places changed

3.3 Client-Side Optimizations

1. Sync Strategy

   • Modify the existing sync logic to use the new Sync Resources API
   • Implement intelligent sync scheduling based on appointment proximity and data staleness

2. Feature Flag Integration

   • Implement UI changes that adapt based on enabled features
   • Ensure graceful degradation when features are disabled or unavailable

3.5 Resource Lifecycle Management

1. Time-based Resource Expiration

   • Implement a system to track the age of each synced resource
   • Set expiration timestamps for resources based on the configured sync time frame (e.g., one week)

2. Automated Cleanup Process

   • Develop a background service to regularly scan for and remove expired resources
   • Schedule the cleanup process to run during low-usage periods to minimize impact on app performance

3. Prioritized Resource Retention

   • Implement a prioritization system to retain critical resources even if they're outside the current time frame
   • Allow for manual overrides to keep specific resources regardless of age

4. Sync Window Sliding

   • As new resources are synced, slide the sync window forward
   • Remove resources that fall outside the new sync window, unless prioritized for retention

5. Cleanup Logging and Reporting

   • Implement detailed logging of cleanup operations
   • Develop a reporting mechanism to track storage usage over time and the effectiveness of the cleanup process

6. User Notification System

   • Create a notification system to inform users about potential data loss due to cleanup
   • Provide options for users to manually retain or re-sync specific data if needed

3.5 Performance Monitoring

1. Custom Analytics

   • Implement custom analytics to track sync performance, API response times, and user interactions with new features
   • Use this data to continually optimize the application

2. Error Tracking

   • Enhance error logging to capture sync issues, API failures, and offline mode problems
   • Implement a system to report critical errors to a monitoring service for quick response

4. Testing Strategy

• Unit tests for new sync algorithms and data handling logic.
• Integration tests for new features and modified components.
• Performance tests to ensure the application meets performance requirements under various network conditions and data loads.
• User acceptance testing (UAT) to validate the new features and workflows.

5. Phased Implementation Plan

To ensure a smooth transition and allow for incremental releases, we propose the following phased implementation approach (NOTE: some of these phases can be done concurrently depending on how we layer our work):

Phase 1: Core Sync Strategy Overhaul

1. Update the app configurations

   • Update the configuration for the app to support facility-based features
   • Update the Configuration Manager in the app

2. Implement New Sync Strategy

   • Develop custom server-side API for syncing resources
   • Modify client-side sync logic to use new API
   • Implement time-based syncing for patients with appointments

3. Implement online search in the search bar

   • Add the ability to search for patients on the server
   • Download the patient data from the server when then patient is requested

4. Update Patient Picker

   • Modify to fetch data directly from the server
   • Implement caching for frequently accessed patient data

5. Basic Resource Lifecycle Management

   • Implement simple time-based expiration for resources
   • Create a basic cleanup process for expired resources

6. Testing and Deployment

   • Thorough testing of new sync strategy
   • Initial release with new sync strategy

Phase 2: Enhanced Patient Management

1. On-Demand Patient Fetching

   • Develop UI for searching and fetching patients not in the current sync window
   • Implement background sync for selected patients

2. Testing and Deployment

   • User acceptance testing for new patient management features
   • Release update with enhanced patient management

Phase 3: List Optimizations and Bulk Operations

1. Custom Configurations for List Pages

   • Implement server-side pagination for large datasets
   • Develop Flattened Tracing List API
   • Update client-side list views to use new APIs

2. Bulk Patient Sync

   • Create UI for selecting multiple patients for sync
   • Implement background service for bulk sync operations

3. Advanced Resource Lifecycle Management

   • Enhance the cleanup process with prioritized resource retention
   • Implement storage optimizations (compression, separate storage for infrequent data)

4. Testing and Deployment

   • Performance testing for list pages and bulk operations
   • Gradual rollout of list optimizations and bulk sync features

Phase 4: Performance Enhancements and Monitoring

1. Implement Performance Monitoring

   • Set up custom analytics for sync performance and API response times
   • Enhance error tracking and reporting

2. User Notification System

   • Develop a system to inform users about data cleanup and sync status

3. Final Testing and Full Deployment

   • Comprehensive testing of all features
   • User training and documentation updates
   • Full deployment to all high-resource facilities

Ongoing: Iterative Improvements

• Gather user feedback after each phase
• Adjust upcoming phases based on real-world performance and user needs
• Continuously monitor and optimize based on performance data

This phased approach allows for the core sync strategy to be implemented and released first, providing immediate benefits to high-resource facilities. Subsequent phases build upon this foundation, adding more advanced features and optimizations. Each phase includes its own testing and deployment steps, allowing for safe, incremental improvements to the application.

Originally posted by @sevenreup in #113