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:

{
  "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 | Next: WebSocket