Harmony Sync

Harmony Sync is Coincert’s iCloud-based cross-device synchronization system. It keeps your financial data in sync across all your Apple devices — iPhone, iPad, and Mac — using Apple’s CloudKit private database.

Harmony Sync keeps your financial data in sync across all your Apple devices via iCloud.

How It Works

Harmony Sync uses Apple’s CKSyncEngine framework to synchronize data through your personal iCloud account. All synced data lives in a dedicated CloudKit zone within your private database, meaning only you can access it.

Key technical details:

• Automatic sync: Changes are detected and uploaded automatically within 2 seconds of any local edit.
• Background sync: On iOS and iPadOS, Coincert registers for background refresh to sync even when the app is not in the foreground.
• Incremental: Only changed records are synced, not the entire database. Harmony Sync tracks what has changed since the last successful sync and sends only the delta.
• Offline-capable: When you are offline, changes are queued locally and uploaded automatically when connectivity returns.

Initial Sync

When you install Coincert on a new device and sign in with the same iCloud account:

1. Harmony Sync detects the existing CloudKit zone from your other devices.
2. It downloads all records from iCloud and creates corresponding local models.
3. The sync status shows “Syncing…” during this process.
4. Once complete, status changes to “Up to date” and all your data is available locally.

If this is your first device, Harmony Sync creates the CloudKit zone and begins uploading your local data. Subsequent devices will pull from this zone.

Sync Status Indicators

Harmony Sync shows its current state using a color-coded status indicator. This appears both on the Dashboard (as the Harmony Sync widget) and in the Harmony Sync settings screen.

Pending Changes Badge

When local changes are waiting to be uploaded, a blue badge appears showing the count of pending changes (e.g., “3” with an up-arrow icon). These changes will sync automatically when the device is online and no errors are blocking sync.

Sync Progress

When a sync operation is in progress, a progress message appears below the status indicator showing what Harmony Sync is currently doing (e.g., “Fetching records…”, “Saving 5/20…”). This message clears when sync completes or when an error occurs.

Last Sync Time

The settings screen shows when the last successful sync occurred in relative format (e.g., “2 min ago”, “1 hour ago”, or “Never synced” if sync has not completed yet).

Quota Warning

If your iCloud storage is nearly full (over 90% capacity), a warning banner appears in the Harmony Sync settings. Sync operations may fail if iCloud storage is completely exhausted. Free up iCloud storage or upgrade your plan to resolve this.

Conflict Resolution

When the same record is edited on two devices before either syncs, a conflict occurs. Harmony Sync detects these automatically and presents them for your review.

How conflicts are handled:

1. Harmony Sync identifies that the local record and the server record have diverged.
2. A conflict notification is sent (if notifications are enabled).
3. A blocking conflict resolution screen appears showing both versions side by side.
4. For each conflicting field, you can see the local value and the server value, with differences highlighted.
5. You choose which version to keep:
   • Keep Local — your device’s version is re-uploaded to iCloud, overwriting the server copy.
   • Accept Server — the iCloud version overwrites your local copy.

Conflicts are resolved one at a time. If multiple conflicts exist, you will see a count and work through them sequentially. Normal app usage resumes after all conflicts are resolved.

Bulk Conflict Resolution

When many conflicts accumulate (e.g., after being offline for an extended period), resolving them one by one can be tedious. The Sync Debug screen (accessible from Harmony Sync settings) provides two bulk actions:

• Accept All Server — overwrites all local versions with the iCloud versions for every pending conflict
• Keep All Local — keeps your local versions and pushes them to iCloud for every pending conflict

Both actions require confirmation and show the count of conflicts that will be affected. Use with caution — bulk resolution cannot be selectively undone.

Conflict Undo

After resolving a conflict (individually or in bulk), you can undo the resolution from the Conflict History. Undoing a resolution restores the local snapshot data that was captured at the time of the conflict and queues the restored record for sync.

Conflict History

Conflict History retains a log of all resolved conflicts for 30 days. After 30 days, conflict logs are automatically cleaned up. Each entry shows:

• The record type and conflicting fields
• Whether the conflict was from a family member or another device
• Which version was kept (local or server)
• Snapshots of both versions at the time of conflict

What can conflict:

Any synced record type can conflict — accounts, transactions, budgets, categories, recurring rules, BNPL loans, debt plans, rename rules, and more. The conflict screen shows the relevant fields for each record type (e.g., name and balance for accounts, payee and amount for transactions).

Push All Data

The Push All Data to iCloud button in Harmony Sync settings forces a full re-upload of every local record to iCloud. This is useful when:

• You suspect data is missing from iCloud after a sync error
• A new device is not receiving all records during initial sync
• You want to ensure iCloud has a complete, fresh copy of everything

This operation uploads all records, not just changed ones. It may take some time if you have a large number of accounts and transactions.

How to use it:

1. Open Settings > Harmony Sync.
2. Scroll to the Diagnostics section.
3. Tap Push All Data to iCloud.
4. Wait for the operation to complete (a spinner indicates progress).

Reset Sync & Refetch All

The Reset Sync & Refetch All button clears your local sync state (change tokens, pending changes) and re-downloads everything from iCloud. This is useful when:

• Sync state becomes corrupted or out of date
• Data appears inconsistent between devices despite showing “Up to date”
• After a database wipe is detected (Coincert automatically resets sync state in this case)

Safety net: Before performing the reset, Coincert automatically creates a backup snapshot (labeled “Auto: before sync reset”). You can restore from this backup if the refetch brings in unexpected data.

How to use it:

1. Open Settings > Harmony Sync.
2. Scroll to the Diagnostics section.
3. Tap Reset Sync & Refetch All.
4. Read the confirmation dialog — local changes not yet synced may be overwritten.
5. Tap Reset & Refetch to confirm.

Retry Sync

When Harmony Sync encounters errors, it uses exponential backoff — waiting progressively longer between retry attempts to avoid flooding a temporarily unavailable service.

Automatic backoff schedule:

Retry Exhaustion

After 10 consecutive failures, Harmony Sync pauses automatically and stops retrying. The status changes to “Sync error” and a notification is sent.

• Passive recovery: After 24 hours, Harmony Sync automatically resets the failure counter and attempts sync again.
• Manual recovery: You can retry immediately by tapping Re-enable Sync or Sync Now in settings, which resets the counter.
• Notification: When sync recovers after being in a failure state, a “Sync Restored” notification is sent.

Manual retry:

You can bypass the backoff timer and retry immediately in two ways:

• From the Dashboard: If the Harmony Sync widget shows an error, tap the Retry Harmony Sync button that appears.
• From Settings: Open Harmony Sync settings and tap Re-enable Sync (appears only when in error state) or Sync Now.

Both options reset the failure counter and attempt sync immediately.

Zone Recreation Safety

If iCloud deletes the sync zone (due to user action in iCloud settings or a server-side issue), Harmony Sync automatically recreates it. However, to prevent infinite recreation loops, a circuit breaker limits zone recreation to 3 attempts per 24-hour window. If this limit is reached, sync pauses and an error is shown asking you to check your iCloud settings.

Offline Mode

Harmony Sync works seamlessly offline:

1. Making changes offline: All edits are saved locally and queued as pending changes. You will see the pending changes count increase in the Harmony Sync widget.
2. Reconnecting: When your device regains network connectivity, Harmony Sync automatically detects the reconnection and begins uploading queued changes.
3. No data loss: Offline changes are persisted across app launches. Even if you close and reopen Coincert while offline, your pending changes are preserved.

The Harmony Sync settings screen shows your current network status:

• Network: Wi-Fi, Cellular, Wired Ethernet, or disconnected
• Cellular Data: Shown when syncing over cellular (may use mobile data)
• Low Data Mode: Shown when the device has Low Data Mode enabled

What Data Syncs

Harmony Sync keeps the following data types in sync across your devices:

Privacy and The Vault

Harmony Sync encrypts sensitive financial fields before they leave your device using CloudKit’s encrypted values container. This is The Vault — field-level encryption that protects your most sensitive data.

What The Vault Encrypts

Non-sensitive fields (like record type identifiers, dates, boolean flags, and color codes) are stored as standard CloudKit fields.

Advanced Data Protection (ADP)

With standard iCloud, Apple manages the encryption keys for your CloudKit data. This means Apple could theoretically access your data if legally required.

With Advanced Data Protection enabled, the encryption keys are protected by your device passcode and stored only on your devices. Not even Apple can decrypt your data.

Requirements for ADP:

• All devices on your iCloud account must run iOS 16.2+, iPadOS 16.2+, or macOS 13.1+
• You must set up a recovery contact or a 28-character recovery key

iPhone: You can open ADP settings directly from Harmony Sync settings via the Open ADP Settings button, or navigate manually to Settings > Apple ID > Advanced Data Protection.

Mac: Navigate to System Settings > Apple ID > Advanced Data Protection.

For more information, visit Apple Support: Advanced Data Protection.

Check iCloud Directly

The Harmony Sync settings include a Check iCloud Directly diagnostic button. This performs a raw CloudKit query (bypassing the sync engine) to verify what data actually exists in your iCloud zone.

Results include:

• Whether the CloudKit zone exists
• Total record count and breakdown by type
• Account details (name, type, balance type) to verify encrypted fields are readable

This is primarily a diagnostic tool for verifying that sync is working correctly.

Troubleshooting

”Sign in to iCloud” status

Cause: No iCloud account is signed in on this device.

Fix: Open your device’s Settings, sign in to your Apple ID, and ensure iCloud is enabled. Harmony Sync will detect the account and begin syncing automatically.

”Sync error” status

Cause: One or more sync operations failed. The specific error message appears in red text below the sync status in settings.

Fix:

1. Check your network connection in the Connection section of Harmony Sync settings.
2. Tap Re-enable Sync or Sync Now to retry immediately.
3. If errors persist, try Push All Data to iCloud from the Diagnostics section.

Data missing on a new device

Cause: Initial sync may not have completed, or data was not fully uploaded from the source device.

Fix:

1. On the source device (where data exists), open Harmony Sync settings.
2. Verify status shows “Up to date” with no pending changes.
3. If pending changes exist, tap Sync Now and wait for completion.
4. If status is “Up to date” but data is still missing on the new device, tap Push All Data to iCloud on the source device.
5. On the new device, tap Sync Now to pull the latest data.

Sync stuck or very slow

Cause: Large number of records, poor network conditions, or Low Data Mode restricting background transfers.

Fix:

1. Ensure you are on a stable Wi-Fi connection.
2. Check if Low Data Mode is enabled (shown in the Connection section) and consider disabling it temporarily.
3. Keep the app in the foreground during initial sync of large datasets.

Conflicts appearing frequently

Cause: Editing the same records on multiple devices in quick succession before sync completes.

Fix: After making changes on one device, wait for the Harmony Sync status to show “Up to date” before editing the same data on another device. If conflicts do arise, resolve them through the conflict resolution screen. If many conflicts have accumulated, use bulk conflict resolution from the Sync Debug screen to resolve them all at once.

Sync stopped after many failures

Cause: 10 consecutive sync failures triggered retry exhaustion.

Fix:

1. Check your network connection and iCloud account status.
2. Harmony Sync will automatically retry after 24 hours.
3. To retry immediately, open Harmony Sync settings and tap Re-enable Sync or Sync Now.
4. If the error persists, check if your iCloud storage is full (a quota warning may appear in settings).

”Zone keeps being deleted” error

Cause: The iCloud sync zone was recreated more than 3 times in 24 hours, triggering the circuit breaker.

Fix:

1. Check your iCloud settings to ensure you haven’t deleted the Coincert data zone manually.
2. Wait 24 hours for the circuit breaker to reset.
3. If the problem persists, contact support — the issue may be server-side.

Recovering from data loss

Fix:

1. Check Settings > Data > Backups for available snapshots (including auto-backups).
2. Restore from the most recent backup that contains your data.
3. After restarting, use Push All Data to iCloud to ensure iCloud matches your restored data.
4. If no backups exist, check if you have a Full Backup export (.coincert file) saved elsewhere.

For complete backup and recovery documentation, see Backup & Recovery.

Data Protection

Beyond iCloud encryption, Coincert provides local backup and recovery tools to protect against data loss. See Backup & Recovery for complete documentation on:

• Database snapshots — point-in-time copies of your entire database
• Auto-backups — automatic snapshots before destructive operations
• Full Backup export — portable JSON export of all 26 data types
• Fresh Start — TestFlight-only feature to simulate a new device

Platform Differences