Cloud sync and offline behaviour

FreelancerFlow is offline-first. Every action you take — adding a client, generating tasks, recording a payment — writes to your phone's local database first. Sync to the cloud happens in the background and never blocks the UI.

The flow

You tap Save in any form. The change is written to your local database immediately.
The change is queued for sync.
As soon as the device has network, the queued change is pushed to the cloud.
On every cold launch and foreground resume, the app also pulls changes from the cloud that happened on your other devices.

This means the app is fully usable on a plane, in a basement, or anywhere else with no signal. Edits made while offline land in the queue and ship the moment you reconnect.

What's synced

Everything that matters: clients, projects, tasks, quotes, quote line items, invoices, invoice line items, payments. Sync happens at the row level — changing one field on one client only pushes that change, not the whole database.

What's NOT synced

Local settings like appearance and language are device-local. Each device has its own preferences.
Drafts of AI Fill Tasks output that you haven't tapped Save tasks on — those live only in the screen state. Close the screen, lose the draft.
Logs and telemetry are kept on-device only; they're not part of the sync stream.

Conflict resolution

When two devices change the same row at almost the same time, FreelancerFlow uses last write wins based on the server-recorded timestamp. The newer change overwrites the older one.

This is a deliberate trade-off — it's simple and predictable. The downside is that if both devices were offline and edited the same field, one edit silently overwrites the other when they reconnect. Workaround: sync each device when you start using it, then edit.

What is missing today

No offline indicator in the UI. The app does not show a "you're offline" banner. If you want to confirm something synced, pull-to-refresh the relevant list after reconnecting — the refresh forces a pull.
No sync history. You can't see "this row changed at 14:32 on device B." Only the current state is visible.
No conflict resolution UI for the user. Conflicts are resolved silently by server timestamp; you don't get a chance to merge manually.

These are intentional V1 simplifications. The two of them mean that for now, the safest pattern is to work on one device at a time if you're editing the same record across multiple devices.

Backup and restore

In addition to cloud sync, FreelancerFlow exports a full local backup as a JSON file:

Settings → Data → Export all data writes a single JSON file with every client, project, task, quote, invoice and payment. Share it through the iOS share sheet — email, Files, AirDrop, anything.
Settings → Data → Import from backup restores from a JSON file. Replace-all semantics: everything currently on the device is overwritten by the file's contents. The app warns you before going through with it.

Backups are mainly useful for moving between devices or keeping an off-cloud copy. For day-to-day use, cloud sync covers what you need.

Sign-out behaviour

When you sign out, the app:

Pushes any queued changes that haven't synced yet.
Signs you out of the server.
Wipes the local database. The next launch starts in an anonymous, empty state.

Sign back in on the same device and the data flows back down from the cloud. Sign in on a new device and the cloud pulls down to that device.

Troubleshooting

Not seeing changes from my other device. Pull-to-refresh the relevant list. Foreground-resume sync runs on a five-second debounce, so an immediate switch between devices may not show changes for a few seconds.
Edits seem to disappear after signing in. If you had data on the new device under an anonymous session, the app prompts you to Keep cloud or Replace cloud during the migration. Both options are non-destructive of cloud data — Replace cloud uploads the anonymous data, Keep cloud drops it.
Same field changed on two devices. Server-newest wins. There is no merge UI.