> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.ttr.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync

> Understanding synchronization in Zeus

## Overview

**Sync** is the process of keeping local data consistent with the server. Zeus uses a local-first approach where changes are made locally first, then synchronized in the background.

## How Sync Works

### The Sync Cycle

1. **Local Change** - User creates/updates/deletes an entity
2. **Queue for Sync** - Entity marked with `syncStatus`
3. **Background Sync** - App attempts to sync when online
4. **Server Update** - Server processes the change
5. **Confirmation** - Local entity updated with `serverId` and `synced` status

### Sync Status Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending_create : User creates
    pending_create --> synced : Server confirms
    synced --> pending_update : User edits
    pending_update --> synced : Server confirms
    synced --> pending_delete : User deletes
    pending_delete --> [*] : Server confirms
    pending_delete --> hidden : Soft delete
    hidden --> [*] : Hard delete

    note right of hidden
        Hidden from queries
        but stored locally
    end note
```

## Sync States

### synced

The entity is in sync with the server. No action needed.

### pending\_create

A new entity that hasn't been created on the server yet.

### pending\_update

An existing entity that has been modified locally and needs to update the server.

### pending\_delete

An entity marked for deletion. Will be hard-deleted after server confirmation.

## Triggering Sync

### Automatic Sync

Sync runs automatically on app startup:

```dart theme={null}
// In bootstrap.dart
await cache.initializeSync();
```

### Manual Sync

Trigger sync manually:

```dart theme={null}
final result = await cache.sync();

if (result.success) {
  print('All changes synced!');
} else {
  print('Sync failed: ${result.error}');
}
```

### Listening to Progress

```dart theme={null}
cache.syncProgress?.listen((progress) {
  print('${progress.step}: ${progress.percent}%');
  print('Items: ${progress.processedItems}/${progress.totalItems}');
});
```

## Sync Order

Entities sync in dependency order:

1. **Categories** - No dependencies
2. **Wallets** - No dependencies
3. **Transactions** - Depends on wallets and categories

This ensures foreign key references are valid when transactions sync.

## Conflict Resolution

### Last-Write-Wins

When the same entity is modified on multiple devices:

1. Server compares `updated_at` timestamps
2. Latest change wins
3. Outdated clients receive the current state on next sync

### Example Scenario

```mermaid theme={null}
sequenceDiagram
    participant DeviceA as Device A
    participant Server
    participant DeviceB as Device B

    Note over DeviceA,DeviceB: Last-Write-Wins Conflict Resolution

    DeviceA->>Server: Update wallet (10:00 AM)<br/>Balance: $100

    DeviceB->>Server: Update wallet (10:05 AM)<br/>Balance: $150
    Note right of Server: Latest timestamp wins<br/>Balance: $150

    DeviceA->>Server: Sync (10:10 AM)
    Server-->>DeviceA: Current state<br/>Balance: $150
    Note left of DeviceA: Receives updated state
```

## Handling Failures

### Retry Logic

Failed operations are automatically retried:

1. Immediate retry on transient errors (network timeout)
2. Exponential backoff for persistent errors
3. Queue preserved across app restarts
4. User can trigger manual retry

### Error Types

| Error                  | Handling              |
| ---------------------- | --------------------- |
| Network timeout        | Retry immediately     |
| Server error (5xx)     | Retry with backoff    |
| Validation error (4xx) | Log error, skip retry |
| Authentication error   | Pause sync, re-auth   |

## Offline Behavior

### What Works Offline

* ✅ Creating wallets, categories, transactions
* ✅ Reading all cached data
* ✅ Updating existing entities
* ✅ Deleting entities (soft delete)

### What Requires Connection

* ❌ Initial data fetch (first install)
* ❌ Syncing pending changes
* ❌ Multi-device consistency

## Best Practices

1. **Always handle sync failures gracefully** - Don't block UI
2. **Show sync status** - Users should know if data is pending
3. **Respect user bandwidth** - Batch sync operations
4. **Test offline scenarios** - Ensure app works without network

## Monitoring Sync

Track these metrics:

* Pending operations count
* Sync success rate
* Average sync latency
* Conflict frequency

## Related

* [Architecture](/getting-started/architecture) - System design
* [Flutter Cache](/flutter/cache/overview) - Implementation details