Cloud Sync Guide - NateEaton/mind-pwa GitHub Wiki

Using the Cloud for Cross-device Synchronization

This guide explains how to use cloud synchronization to access your MIND Diet tracking data across multiple devices.

Overview

Cloud synchronization allows you to:

  • Access your data anywhere: Track on your phone during meals, review on your tablet, check history on your computer
  • Automatic backup: Your tracking data is safely stored in your personal cloud account
  • Seamless device switching: Start tracking on one device, continue on another without missing a beat
  • Never lose progress: Even if you lose your device, your data is preserved in the cloud

Important: Cloud sync is only available in server-enabled deployments. If you're using the hosted demo or a client-only deployment, you can use the import/export features for data portability instead.

Self-Hosting: If you want to set up your own server-enabled instance, see the Installation Guide for complete setup instructions.

Supported Providers

Google Drive

  • Your tracking data is stored in a private app folder in your Google Drive
  • Not visible in your regular Drive file listing
  • Requires a Google account

Dropbox

  • Your tracking data is stored in a dedicated app folder in your Dropbox
  • Only accessible by the MIND Diet Tracker app
  • Requires a Dropbox account

Setting Up Cloud Sync

During First-Time Setup (Recommended)

The easiest time to enable cloud sync is when you first open the app:

  1. Complete the setup wizard steps
  2. When asked about cloud sync, choose "Yes, enable cloud sync"
  3. Select your preferred provider (Google Drive or Dropbox)
  4. Click "Connect" and complete the authentication process
  5. You'll be redirected back to the app with sync enabled

For Existing Users

If you've already been using the app locally, you can enable cloud sync anytime:

  1. Open the Menu (⋮) and select "Settings"
  2. In the Cloud Synchronization section, check "Enable cloud sync"
  3. Select your preferred provider
  4. Click "Connect" to start the authentication process
  5. Complete the authentication and return to the app
  6. Your existing data will be uploaded to the cloud on the first sync

How Sync Works

Automatic Synchronization

Cloud sync happens automatically:

  • When you open the app on any device
  • When you go online after being offline
  • After making changes to your tracking data
  • Periodically in the background while the app is open

Manual Synchronization

You can also sync manually anytime:

  • Click "Sync Now" in Settings
  • Select "Sync Now" from the main menu
  • Useful for ensuring data is up-to-date before closing the app

What Gets Synced

Your MIND Diet tracking data:

  • Daily food counts for the current week
  • Historical data from previous weeks
  • Weekly reset information and archival data

Note: App preferences (like theme settings and first day of week) are stored locally on each device and do not sync between devices.

Using Multiple Devices

First Device Setup

  1. Enable cloud sync and authenticate with your chosen provider
  2. Your data will be uploaded to the cloud
  3. Continue tracking normally

Additional Devices

  1. Open the app on your new device
  2. Complete the setup wizard and enable cloud sync
  3. Choose the same provider and authenticate with the same account
  4. Your data will automatically download and sync

Switching Between Devices

Seamless experience: You can freely switch between devices - your data stays in sync automatically.

Example workflow:

  • Log breakfast on your phone at home
  • Check weekly progress on your computer at work
  • Add dinner servings on your tablet in the evening
  • All devices show the same up-to-date information

Sync Status Indicators

In Settings

  • Connected: Sync is enabled and working
  • Not connected: Authentication needed or expired
  • Syncing...: Sync operation in progress
  • Offline: No internet connection

Visual Feedback

  • Toast notifications: Brief messages when sync completes or encounters issues
  • Sync progress: Visual indicators during sync operations
  • Error alerts: Clear messages if sync fails with suggested actions

Conflict Resolution

When Conflicts Happen

Conflicts occur when you make changes on multiple devices while offline:

  • You add food counts on your phone (offline)
  • Meanwhile, you add different counts on your tablet (also offline)
  • When both devices come online, the app needs to resolve the differences

How Conflicts Are Resolved

The app uses intelligent rules to merge your data safely:

Primary: Most recent change wins

  • The latest modification timestamp determines which data takes precedence

Secondary: The higher value wins (only when timestamps match exactly)

  • If you logged 2 servings of nuts on one device and 3 on another, you'll end up with 3
  • This ensures you never lose recorded servings
  • This only applies when timestamps are identical (very rare)

Weekly Resets: Reset takes priority

  • If one device has reset to a new week while another hasn't, the reset is preserved
  • Ensures weekly archiving works correctly across devices

Behind the Scenes: Conflict resolution happens automatically and silently. The app logs resolution details for debugging but doesn't interrupt your experience with notifications.

Network and Data Settings

Wi-Fi Only Mode

To conserve mobile data:

  1. Open Settings
  2. Enable "Sync only on Wi-Fi"
  3. Sync will pause when you're on cellular data
  4. Resumes automatically when you connect to Wi-Fi

Data Usage

Cloud sync is designed to be data-efficient:

  • Only changed data is uploaded/downloaded
  • Typical sync operations use minimal bandwidth
  • Historical data syncs once, then only updates changes

Privacy and Security

Your Data, Your Control

  • Personal cloud storage: Data goes only to your Google Drive or Dropbox account
  • No third-party access: The app doesn't share data with anyone else
  • Limited app access: The app can only access its own folder in your cloud account
  • Local-first: All data stays on your device; cloud is just a backup/sync mechanism

Authentication Security

  • Secure OAuth: Industry-standard authentication prevents password sharing
  • Server-side secrets: Sensitive credentials never exposed in your browser
  • Token management: Authentication tokens are handled securely
  • Automatic refresh: Expired tokens are renewed automatically

Privacy Features

  • No analytics: The app doesn't track your usage or collect analytics
  • No advertising: No ads or tracking scripts
  • Open source: Complete code is available for review
  • Disconnect anytime: You can disable sync and keep your local data

Troubleshooting

Sync Not Working

Check internet connection:

  • Ensure your device is online
  • Try visiting other websites to verify connectivity

Verify authentication:

  • Go to Settings and check sync status
  • If "Not connected," click "Connect" to re-authenticate

Try manual sync:

  • Use "Sync Now" to force synchronization
  • Check for specific error messages

Authentication Issues

Google Drive problems:

  • Ensure you're signed in to the correct Google account
  • Check that popup blockers aren't preventing authentication
  • Try signing out and back in to Google

Dropbox problems:

  • Verify you're signed in to the correct Dropbox account
  • Complete the full authentication process on the Dropbox page
  • Don't close the browser window during authentication

Data Missing After Sync

Check the correct account:

  • Verify you're authenticated with the same cloud account on all devices
  • Different accounts will have different data

Look in History view:

  • Your data might be in a previous week
  • Use the date navigation to check different time periods

Try disconnecting and reconnecting:

  • Disable cloud sync in Settings
  • Re-enable and authenticate again
  • This often resolves token or permission issues

Performance Issues

Slow sync:

  • Check your internet connection speed
  • Enable "Wi-Fi only" mode for better performance
  • Large amounts of historical data may take time on first sync

Frequent disconnections:

  • Clear your browser cache
  • Check if your internet connection is stable
  • Try re-authenticating with your cloud provider

Disconnecting Cloud Sync

If you want to stop using cloud sync:

  1. Go to Settings
  2. Uncheck "Enable cloud sync"
  3. Your local data remains unchanged
  4. Cloud data stays in your account but won't sync anymore

Switching Cloud Providers

To change from Google Drive to Dropbox (or vice versa):

  1. Export your data first (recommended)
  2. Disable current cloud sync
  3. Enable sync with the new provider
  4. Your data will upload to the new provider on first sync