immish/docs/background-services.md

# Background Services

The app runs various background services to sync photos, perform backups, and maintain data consistency without requiring user interaction.

## Background Backup Service

The background backup service automatically uploads photos to the server when the app is not in the foreground.

### Platform Channel Communication

The app uses platform-specific channels to communicate with native background services:

**Channel Name:** `immich/foregroundChannel`

**Methods:**

| Method | Direction | Purpose |
|--------|-----------|---------|
| `initialized` | Native → App | Notify app that background service started |
| `start` | App → Native | Start background backup |
| `stop` | App → Native | Stop background backup |
| `updateNotification` | App → Native | Update progress notification |
| `systemStop` | Native → App | System stopped the service |

### Notification Structure

Background backup shows progress notifications:

**Notification Data:**
```json
{
  "title": "Backup Progress",
  "content": "Uploading photo 5 of 100",
  "progress": 5,
  "max": 100,
  "indeterminate": false,
  "isDetail": true
}
```

**Notification Types:**
- **Total Progress**: Overall backup progress (X of Y files)
- **Single Progress**: Current file upload progress (percentage)
- **Error Notification**: Shows when upload fails

### Background Service Lifecycle

```
App Backgrounded
       │
       ▼
┌─────────────────┐
│ Service Starts  │
│ (initialized)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Check Conditions│
│ - WiFi required?│
│ - Charging?     │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 Proceed    Wait
    │
    ▼
┌─────────────────┐
│ Find Upload     │
│ Candidates      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Upload Files    │◄──────┐
│ One by One      │       │
└────────┬────────┘       │
         │                │
         ▼                │
┌─────────────────┐       │
│ Update Notif.   │───────┘
│ Progress        │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 More      Complete
 Files        │
    │         ▼
    │    ┌─────────────────┐
    └───►│ Service Stops   │
         └─────────────────┘
```

### Settings

| Setting | Description | Default |
|---------|-------------|---------|
| `backgroundBackup` | Enable/disable background backup | false |
| `backupRequireWifi` | Only backup on WiFi | true |
| `backupRequireCharging` | Only backup while charging | false |
| `backupTriggerDelay` | Minutes before starting backup | 30 |
| `backgroundBackupTotalProgress` | Show total progress notification | true |
| `backgroundBackupSingleProgress` | Show per-file progress | false |

### Error Handling

**Grace Period for Notifications:**
- Errors don't immediately show notification
- `uploadErrorNotificationGracePeriod` setting controls delay (default: 2 uploads)
- Prevents notification spam for transient errors

**Error Recovery:**
- Service tracks `backupFailedSince` timestamp
- Retries on next service run
- User notified after grace period exceeded

## Sync Service

Keeps local database synchronized with server.

### Sync Operations

1. **Asset Sync**: Download remote asset metadata
2. **Album Sync**: Sync album memberships and contents
3. **User Sync**: Sync user and partner information

### Sync Flow

```
┌─────────────────┐
│  Sync Trigger   │
│  (App Start /   │
│   WebSocket)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Fetch Remote    │
│ Changes (ETag)  │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 Changes    No
 Found    Changes
    │         │
    ▼         │
┌─────────────────┐
│ Process Deltas  │
│ - New assets    │
│ - Updated assets│
│ - Deleted assets│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Update Local DB │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Refresh UI      │
└─────────────────┘
```

### ETag-Based Sync

The app uses ETags to efficiently detect changes:

1. Store ETag from last sync
2. Send ETag in request header
3. If server returns 304 (Not Modified), skip sync
4. If server returns new data, update local cache and ETag

### Remote Asset Removal

When assets are deleted on server:
1. Receive list of deleted asset IDs
2. Remove from local database
3. Update timeline display
4. Keep local-only assets intact (if any)

## WebSocket Events for Background Sync

Real-time events that trigger sync operations:

| Event | Action |
|-------|--------|
| `on_upload_success` | Add new asset to timeline |
| `on_asset_delete` | Remove asset from local DB |
| `on_asset_trash` | Move asset to trash |
| `on_asset_restore` | Restore asset from trash |
| `on_asset_update` | Refresh asset metadata |
| `on_asset_hidden` | Remove from visible timeline |

## Foreground Upload Service

For uploads while app is visible:

### Features
- Shows upload progress in UI
- Can be paused/cancelled by user
- Uses foreground service notification
- Continues if user switches apps briefly

### Progress Tracking

```
Upload State:
- totalCount: Total files to upload
- completedCount: Successfully uploaded
- failedCount: Failed uploads
- currentFile: File being uploaded
- currentProgress: 0-100 percentage
```

## App Lifecycle Integration

### On App Resume
1. Reconnect WebSocket
2. Refresh authentication
3. Trigger quick sync
4. Resume any pending uploads

### On App Pause
1. Start background service (if enabled)
2. Save current state
3. Disconnect WebSocket (after delay)

### On App Terminate
1. Complete current upload (if possible)
2. Schedule background task
3. Clean up resources

## Battery Optimization

The background service is designed to be battery-efficient:

- **Batching**: Groups multiple uploads
- **Debouncing**: Waits before processing WebSocket events (5 second debounce)
- **Conditions**: Respects WiFi and charging requirements
- **Scheduling**: Uses system job scheduler when possible

## Debug Logging

Enable advanced troubleshooting in settings to see detailed logs:

| Log Level | What's Logged |
|-----------|---------------|
| INFO | Service start/stop, sync complete |
| WARNING | Retry attempts, partial failures |
| SEVERE | Errors, failed uploads |

---

[Previous: Activities](activities.md) | [Next: WebSocket](websocket.md)