iCloud Sync

How Sync Works

CloudKit Integration

Spool Buddy uses Apple's CloudKit technology to sync your data:

• Automatic: Changes sync in the background without user intervention
• Private: Your data is stored in your personal iCloud account
• Secure: End-to-end encrypted in transit
• Efficient: Only changed data is transferred

What Gets Synced

Everything in your filament inventory syncs:

• Filament entries (polymer, brand, color, weight, etc.)
• Usage logs (all entries with timestamps and notes)
• Drying logs (all drying sessions)
• Modifications and deletions
• Filter preferences and settings

When Sync Happens

Sync occurs automatically when:

• You add, edit, or delete a filament
• You create a usage or drying log
• The app opens
• You switch between apps
• Changes are made on another device

No manual sync trigger is needed - it happens seamlessly in the background.

Requirements

iCloud Account

You must be signed into iCloud on each device:

• iOS/iPadOS: Settings → [Your Name] → iCloud
• macOS: System Settings → Apple ID → iCloud

iCloud Drive Enabled

Make sure iCloud Drive is turned on:

• It's required for CloudKit functionality
• Check the same locations as above
• Ensure iCloud Drive toggle is enabled

Internet Connection

Devices need internet access to sync:

• Wi-Fi: Recommended for large sync operations
• Cellular: Works but may consume data
• Offline: Changes are queued and sync when connection resumes

Sufficient iCloud Storage

Your filament data counts against your iCloud storage quota:

• Typical usage is minimal (a few MB for hundreds of filaments)
• If your iCloud storage is full, sync will fail
• Check: Settings → [Your Name] → iCloud → Manage Storage

Sync Status

Viewing Sync Status

On iOS/iPadOS

1. Tap the info button (ⓘ) in the top-left
2. Scroll to the bottom of the About view
3. You'll see the sync status indicator

On macOS

Look at the bottom of the sidebar for the sync status indicator.

Status Indicators

The sync monitor shows several states:

Syncing

• Indicator: Animated spinner or progress indicator
• Meaning: Data is actively syncing with iCloud
• Action: Wait for it to complete (usually a few seconds)

Synced

• Indicator: Checkmark or "Up to date"
• Meaning: All changes have been uploaded and downloaded
• Action: None needed

Not Syncing

• Indicator: Warning icon or "Not syncing"
• Meaning: Sync is paused or encountering issues
• Action: Check troubleshooting steps below

Error

• Indicator: Error icon with message
• Meaning: Sync has failed
• Action: See error-specific troubleshooting below

Multi-Device Usage

Best Practices

Let Initial Sync Complete

When installing Spool Buddy on a new device:

1. Open the app
2. Wait for the initial sync to complete (may take a minute)
3. Don't immediately add filaments
4. Verify your existing inventory appears

Avoid Simultaneous Edits

While conflict resolution is automatic, it's best to:

• Finish editing on one device before switching to another
• Save changes before putting the device to sleep
• Let sync complete before making edits elsewhere

Trust the Sync

If you make changes on one device:

• They'll appear on other devices within seconds to minutes
• You don't need to force-quit or restart the app
• Changes propagate automatically

Common Scenarios

Adding Filaments on Multiple Devices

You add a filament on your iPhone, then open your Mac:

1. iPhone creates the new filament locally
2. iPhone uploads to iCloud (usually within seconds)
3. Mac receives the update next time it syncs
4. New filament appears in Mac's sidebar automatically

Editing the Same Filament

You edit a filament on iPad while your Mac is also open:

1. iPad saves your changes and uploads them
2. Mac receives the update and refreshes
3. If Mac had the same filament selected, it updates in place
4. If there's a conflict, the most recent change wins

Deleting on One Device

You delete a filament on your Mac:

1. Mac removes it locally and uploads the deletion
2. iPhone and iPad receive the deletion
3. The filament disappears from all devices
4. Associated logs are also removed

Troubleshooting

Changes Not Appearing on Other Devices

Possible causes:

1. Sync hasn't completed yet

   • Wait 1-2 minutes
   • Check sync status on both devices
   • Ensure both devices are online

2. Not signed into iCloud

   • Verify iCloud sign-in on all devices
   • Check that the same Apple ID is used

3. iCloud Drive disabled

   • Enable iCloud Drive in Settings/System Settings
   • Restart the app after enabling

4. Internet connection issues

   • Verify Wi-Fi or cellular connection
   • Try accessing another iCloud-synced app
   • Switch networks if possible

5. iCloud storage full

   • Check iCloud storage in Settings
   • Free up space or upgrade plan
   • Sync will resume when space is available

Solutions:

• Force-quit and reopen the app on both devices
• Toggle Airplane Mode off and on
• Sign out and back into iCloud (last resort)

Duplicate Filaments Appearing

This is rare but can happen if:

• The same filament is added on multiple devices simultaneously
• Sync was interrupted during creation

Solution:

1. Identify the duplicate (usually identical except for usage logs)
2. Decide which to keep
3. Delete the duplicate
4. If needed, manually recreate missing usage logs

Filament Deleted Unexpectedly

If a filament disappeared:

1. Check if it was deleted on another device
2. Verify you're viewing the correct filter/search
3. Wait a minute in case it's a sync delay

If truly deleted by mistake:

• Unfortunately, there's no undo or trash
• You'll need to recreate the filament manually
• Consider duplicating important filaments as backups

Sync Appears Stuck

If the sync indicator stays on "Syncing" for more than a few minutes:

1. Force-quit the app:

   • iOS: Swipe up from app switcher
   • Mac: Quit from menu or Cmd+Q
   • Reopen the app

2. Check iCloud status:

   • Visit Apple System Status
   • Verify iCloud services are operational

3. Restart the device:

   • Sometimes helps clear stuck sync operations

4. Check storage:

   • Ensure sufficient space on device
   • Check iCloud storage quota

Conflicts and Data Loss

Spool Buddy uses CloudKit's automatic conflict resolution:

• Most recent change wins
• Timestamps determine recency
• This is usually what you want

To minimize conflicts:

• Try to edit on one device at a time
• Let sync complete before switching devices
• Don't force-quit the app immediately after changes

If you lose data:

• Unfortunately, there's no version history or backup
• Changes are permanent once synced and deleted
• Consider keeping external backups of critical information

Privacy and Security

Your Data is Private

• Stored in your personal iCloud account
• Not accessible to other users or app developers
• Apple cannot read your filament data (encrypted)

Encryption

• Data is encrypted in transit (TLS)
• Data is encrypted at rest in iCloud
• Only you can access your data with your Apple ID

No Third-Party Servers

• Spool Buddy doesn't use any servers except Apple's iCloud
• No data collection or analytics from your inventory
• No sharing with third parties

Sync Performance

Speed

Typical sync times:

• Single filament: 1-2 seconds
• Usage log entry: < 1 second
• Bulk changes: 5-10 seconds for dozens of filaments
• Initial sync: 30-60 seconds for hundreds of filaments

Data Usage

Filament data is very compact:

• Average filament: < 1 KB
• Hundreds of filaments: < 1 MB total
• Usage logs: < 100 bytes each

Even with cellular data, sync uses minimal bandwidth.

Disabling Sync

Why You Might Want To

• Limited iCloud storage
• Privacy concerns
• Working offline permanently
• Troubleshooting

How to Disable

Currently, Spool Buddy requires iCloud:

• The app is designed for sync-first operation
• There's no offline-only mode
• Signing out of iCloud will prevent the app from functioning properly

Alternative:

• Keep a single device as your primary
• Don't install on other devices
• This effectively disables multi-device sync

Advanced Topics

Multiple Apple IDs

If you use different Apple IDs on different devices:

• Each Apple ID has its own separate iCloud storage
• Filaments won't sync between different Apple IDs
• Consider using Family Sharing (though Spool Buddy data won't share)
• Use one Apple ID across all devices for full sync

Shared Filament Inventory

Currently, Spool Buddy doesn't support sharing your inventory with other users:

• Each user has their own separate inventory
• No family or team sharing features
• Consider manual export/import solutions if needed

Backup

While iCloud provides some redundancy:

• Your data is as safe as your iCloud account
• There's no built-in export to CSV or backup file
• Consider taking screenshots of critical filaments
• Manual backup: Note important filaments in another app

Future versions may add export functionality.

Future Improvements

Potential sync enhancements being considered:

• Conflict resolution UI (choose which version to keep)
• Sync log/history viewer
• Manual sync trigger
• Export/import for backup
• Offline mode with deferred sync

Check for app updates for new features.