Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / sync-and-client-state

Sync and client state

Sync and client state keep a user's photo library consistent across the server, mobile app, and device media store. The system streams ordered changes for remote library data, stores progress per device session, and uses separate activity, notification, and local-media state so each client can resume work without starting from zero.

System boundaries

The sync system has three related but distinct state paths. Remote library data moves through the sync stream. Shared-album activity and user notifications use their own request and event paths. Device media state is reconciled locally because the phone's photo provider is not the same store as the app database.

The main relationships are:

StateMain purposeDurable ownerClient result
Remote library stateKeep assets and their related records currentServer tables and audit recordsMobile remote-data database
Session progressRecord which stream changes a device has appliedServer session and checkpoint recordsResume from the last acknowledged change
Activity stateStore album and asset comments or likesServer activity recordsCached activity view
Notification stateStore user notices and read statusServer notification recordsUnread notification view
Device media stateMatch backup albums with phone mediaDevice media provider and local databaseLocal album and asset records

This separation lets a client refresh one kind of state without treating every state source as one transaction. See Data model and persistence for the wider storage model, Asset organization and discovery for the asset-side view, Mobile library synchronization for mobile workflows, and Web library workflows for web workflows.

Remote and local state

Remote state is the server's view of assets, albums, people, stacks, memories, partner shares, metadata, and related links. The mobile app stores a durable copy of these records so library views can work from local data after the stream has finished. The stream repository applies inserts, updates, and deletes as batches and uses a reset path when the server says that the local copy must be rebuilt (mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L46-L88, mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L217-L310).

The device media provider remains outside that remote copy. Local sync reads albums and media from the platform, compares them with the app's local records, and then records the new checkpoint only after the comparison is applied (mobile/lib/domain/services/local_sync.service.dart#L45-L124). This boundary is important: a remote asset delete can change the device trash state, while a device media change can create a new backup request.

References: mobile/…/sync_stream.repository.dart• L46-88 mobile/…/local_sync.service.dart• L45-124 mobile/…/sync.provider.dart• L13-39

State ownership

The server owns the durable source of truth for remote library records. Each authenticated device session owns its sync progress. The client owns the local projection of remote records and the reconciliation state for device media. These ownership rules prevent a client checkpoint from being mistaken for a global library version.

The server also exposes activity and notification state as user-facing records. Those records are durable on the server but are normally fetched or changed on demand by the web and mobile clients. They do not form part of the mobile remote-library stream (server/…/activity.controller.ts• L23-74, server/…/notification.controller.ts• L22-92).

References: server/…/session.table.ts• L14-51 server/…/sync-checkpoint.table.ts• L15-34 server/…/activity.controller.ts• L23-74 server/…/notification.controller.ts• L22-92

Server sync contract

The server sync contract is a session-scoped, JSON Lines stream. A client chooses the record groups it understands, receives ordered upsert and delete events, and sends back acknowledgements after it has applied each batch. The contract supports versioned record types so an older client can select an older shape while newer clients use updated shapes.

The high-level exchange is:

sequenceDiagram
    participant Client
    participant Stream as Sync stream
    participant Checkpoint as Session checkpoints
    participant Store as Local remote store

    Client->>Stream: Request record types
    Stream->>Checkpoint: Read saved acknowledgements
    Stream-->>Client: Ordered upserts and deletes
    Client->>Store: Apply one type batch
    Client->>Checkpoint: Acknowledge last applied event
    Stream-->>Client: SyncComplete or SyncReset
    Client->>Stream: Request again after reset when needed

The stream is available only to a session token. API keys cannot use it because progress belongs to a device session (server/…/sync.service.ts• L98-110, server/…/sync.controller.ts• L20-71). The request can ask for a reset. The server can also return a reset when a session has a pending reset or when its saved completion point is too old (server/…/sync.service.ts• L160-185, server/…/sync.service.ts• L263-272).

Event families

The contract groups changes by the kind of relationship that the client must keep current. The important families are:

FamilyClient-visible purpose
User and partnerResolve owners, shared users, and partner-library access
Asset and asset detailsReconcile asset identity, file details, EXIF, edits, metadata, and OCR
Album and membershipRebuild shared albums, member roles, and album membership
Album linksKeep album-to-asset and related EXIF links consistent
Memory and stackKeep generated memories and grouped assets current
People and facesKeep person records and face locations current
Control eventsMark backfill checkpoints, request a reset, or mark stream completion

Each family has upsert and, where needed, delete events. Shared assets and album links have backfill events because a client may learn about a new partner or album after the related historical records already exist (server/…/enum.ts• L1013-1140, server/…/sync.dto.ts• L471-527).

References: server/…/enum.ts• L1013-1140 server/…/sync.dto.ts• L471-527 server/…/sync.service.ts• L64-96 server/…/sync.service.ts• L189-225

Ordering and acknowledgements

The server takes one sync point before it reads the requested families. It returns records before that point in ascending update order. This gives one stream a stable upper bound even when new writes happen during the request (server/…/sync.service.ts• L177-187, server/…/sync.repository.ts• L103-144).

An acknowledgement is a compact string that names the event family and its update point. The client sends the last event it has applied for a batch. The server stores one checkpoint per session and event family, replacing the prior value on update (server/…/sync.ts• L11-34, server/…/sync-checkpoint.repository.ts• L13-41). The mobile client applies a same-type batch before it acknowledges that batch (mobile/lib/domain/services/sync_stream.service.dart#L158-L190).

References: server/…/sync.service.ts• L113-145 server/…/sync.service.ts• L177-187 server/…/sync.repository.ts• L103-144 server/…/sync.ts• L11-34 mobile/…/sync_stream.service.dart• L158-190

Backfill and reset

Backfill fills a relationship that the client could not learn from only the latest change point. For example, a newly visible partner or album can require older asset or membership rows. The server marks the end of each relationship backfill with a control acknowledgement, so a later stream does not repeat completed history (server/…/sync.service.ts• L354-411, server/…/sync.service.ts• L525-578).

Reset is the recovery path when the local projection cannot safely continue. The server sends a reset control event. The mobile client clears remote entities, runs the stream again without the reset request, and then rebuilds its local projection from the selected families (mobile/lib/domain/services/sync_stream.service.dart#L79-L104, mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L46-L88).

References: server/…/sync.service.ts• L160-185 server/…/sync.service.ts• L354-411 mobile/…/sync_stream.service.dart• L79-104 mobile/…/sync_stream.repository.dart• L46-88

Client sync libraries

The mobile sync libraries split transport, event application, and device reconciliation. SyncApiRepository handles the HTTP stream and acknowledgement calls. SyncStreamService chooses compatible event families, batches events by type, runs version migrations, and sends records to the local remote store. LocalSyncService compares the phone media store with local backup records.

This split keeps network failure, remote-record application, and device-media differences in separate recovery paths. The provider graph wires these services to the API client, durable database, platform bridge, media store, and cancellation signal (mobile/lib/providers/infrastructure/sync.provider.dart#L13-L39).

Stream client

The stream client requests only the event families supported by the server version. It reads newline-delimited JSON from the response, maps each event type to a typed record, and passes batches to the service layer (mobile/lib/infrastructure/repositories/sync_api.repository.dart#L27-L142). The service then applies one event family at a time and acknowledges only after the local write succeeds (mobile/lib/domain/services/sync_stream.service.dart#L158-L192).

The client also handles schema transitions through targeted acknowledgement deletion. A migration can ask the server to replay a family when a field shape or meaning changed. This makes the next stream act as a controlled rebuild for that family rather than a blind full reset (mobile/lib/domain/services/sync_stream.service.dart#L24-L30, mobile/lib/domain/services/sync_stream.service.dart#L107-L148).

References: mobile/…/sync_api.repository.dart• L27-142 mobile/…/sync_stream.service.dart• L59-104 mobile/…/sync_stream.service.dart• L107-192

Durable remote store

The mobile remote store is the durable projection used by library features. It applies records by stable identity and treats delete events as part of the same contract as upserts. Asset records are kept separate from EXIF, edits, metadata, albums, memberships, and other linked records so each event family can advance independently (mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L232-L372, mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L475-L623).

The store must preserve links while a reset or delete is in progress. Its reset path clears remote records and removes local pointers that would otherwise refer to missing remote albums. This lets the next stream rebuild a valid graph instead of leaving stale links behind (mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L46-L88).

References: mobile/…/sync_stream.repository.dart• L46-88 mobile/…/sync_stream.repository.dart• L232-372 mobile/…/sync_stream.repository.dart• L475-623

Device media reconciliation

Device media reconciliation compares platform albums and assets with the app's local backup records. A delta path handles ordinary changes. A full path compares complete album contents when the platform cannot provide a reliable delta or when the user requests a rebuild (mobile/lib/domain/services/local_sync.service.dart#L45-L146, mobile/lib/domain/services/local_sync.service.dart#L128-L214).

The service also reconciles trash and restore state for backup-enabled media. On Android this requires media-management permission. On iOS, cloud albums need a full album pass because the platform delta does not include all cloud changes (mobile/lib/domain/services/local_sync.service.dart#L48-L111, mobile/lib/domain/services/local_sync.service.dart#L358-L397). See Mobile capture and backup for the upload side of this relationship.

References: mobile/…/local_sync.service.dart• L45-146 mobile/…/local_sync.service.dart• L216-329 mobile/…/local_sync.service.dart• L358-397

Activity state

Activity state represents comments and likes on a shared album or on an asset inside that album. It is an interaction layer over album membership, not a remote-library record family. The server checks album access, enforces one like for a user and scope, and returns activity counts for the client view (server/…/activity.service.ts• L20-74, server/…/activity.table.ts• L20-65).

Activity scope

An activity scope is an album plus an optional asset. A missing asset means the activity belongs to the album. Comments carry text. Likes carry no comment and are unique for a user at that scope (server/…/activity.dto.ts• L7-63).

The web manager keeps the selected scope, list, counts, and current user's like together. It caches these values by album and asset so opening the same view does not require a new request until the cache is invalidated (web/…/activity-manager.svelte.ts• L17-75, web/…/activity-manager.svelte.ts• L140-178). The mobile activity store follows the same scope model and caches records in memory rather than in the remote sync database (mobile/lib/data/store/activity.dart#L10-L45).

References: server/…/activity.dto.ts• L7-63 server/…/activity.table.ts• L20-65 web/…/activity-manager.svelte.ts• L17-75 web/…/activity-manager.svelte.ts• L140-178 mobile/…/activity.dart• L10-45

Notification state

Notification state tells a user about server events such as shared-album invitations, album updates, and selected job or account events. A notification is a durable user record with a type, level, message, optional data, and read time (server/…/notification.dto.ts• L25-45, server/…/notification.table.ts• L16-53).

The server can create a notification and send it over the live client channel. The client can later list unread records, mark one or many as read, or delete them. Event handlers also keep clients aware of asset, session, and album changes through live messages. Album invitations and updates create durable local notices first, then the queued notification job sends email only when the recipient's preferences allow it (server/…/notification.service.ts• L141-185, server/…/notification.service.ts• L219-250, server/…/notification.service.ts• L375-428, server/…/notification.service.ts• L478-497).

The web notification store refreshes unread state after login and clears it on logout. It removes items from the visible list before sending the read request, which keeps the interface responsive while the server stores the read time (web/…/notification-manager.svelte.ts• L7-39).

References: server/…/notification.service.ts• L37-74 server/…/notification.service.ts• L81-109 server/…/notification.service.ts• L141-185 server/…/notification.service.ts• L219-250 server/…/notification.service.ts• L375-428 server/…/notification.service.ts• L478-497 web/…/notification-manager.svelte.ts• L7-39

Session state

Sessions bind authentication to a device or app instance. A session has a token, optional expiry, device details, and a link to its parent session. Its sync checkpoints are separate rows keyed by session and event family, so two devices can consume the same library at different speeds (server/…/session.table.ts• L14-51, server/…/sync-checkpoint.table.ts• L15-34).

Session lifecycle

An authenticated session can create a child session for another device or casting target. Users can list sessions, delete one or all sessions, lock a session, or mark one for a sync reset. Password changes invalidate other sessions, and cleanup removes expired tokens (server/…/session.service.ts• L18-27, server/…/session.service.ts• L30-87).

Session deletion and sync reset have different effects. Deletion removes access to the session. A pending sync reset keeps access but tells the next sync to discard its remote projection and rebuild it (server/…/session.service.ts• L54-71, server/…/sync.service.ts• L160-173).

References: server/…/session.service.ts• L18-87 server/…/session.controller.ts• L21-107 server/…/sync.service.ts• L160-173

Library state

An external library is a server-side view of media in user-managed file paths. It accepts readable absolute directories outside the managed upload folder, then uses import paths and exclusion patterns to create or refresh assets owned by the selected user. The library record reports asset count and refresh time, while the asset records enter the same broader asset and sync model as other server assets (server/…/library.dto.ts• L63-106, server/…/library.table.ts• L15-46, server/…/library.service.ts• L298-337).

Library discovery

Library discovery can run on a schedule, on demand, or from file-watch events. A watcher ignores configured exclusion patterns before it reacts to supported file changes. A scan finds supported files and queues imports. A later asset check marks missing files offline, brings files back online when they return, and queues metadata work when file times change (server/…/library.service.ts• L91-159, server/…/library.service.ts• L615-683, server/…/library.service.ts• L699-760).

The library path is therefore an input to asset state rather than a separate client library. Once an asset is imported, its changes can reach mobile clients through the normal asset event family. If the library is deleted, its assets are marked for deletion and removed through the queued asset lifecycle (server/…/library.service.ts• L363-398). See Asset organization and discovery for the asset-side view.

References: server/…/library.service.ts• L91-159 server/…/library.service.ts• L252-294 server/…/library.service.ts• L615-683 server/…/library.service.ts• L699-760

Change checklist

When these files or sections are changed, remember to consider these:

  • A new or changed sync event needs aligned request and entity names, server payload validation, mobile JSON conversion, and mobile batch application.
  • A payload field change may require a versioned event type plus a client acknowledgement reset or migration task. Do not assume the old checkpoint can safely continue.
  • Changes to event order must preserve dependencies between parent records and links. Album, partner, and relationship backfills depend on their parent creation ranges.
  • Changes to acknowledgement format must stay aligned across serialize, fromAck, checkpoint storage, and the mobile batch acknowledgement boundary.
  • Changes to session reset behavior must cover both the server pending-reset flag and the client remote-store clearing path.
  • Changes to external library import, watch, or exclusion rules must preserve the link from discovered files to asset lifecycle events and offline state.
  • Changes to activity or notification read behavior must keep the API response, client cache removal, and durable read state consistent.
  • Changes to notification event handling must preserve the split between live client messages, durable local notices, delayed email jobs, and recipient preference checks.

Important failure modes

TriggerConsequenceGuard
Client acknowledges a batch before its local write completesA restart can skip records that never reached the local storeApply the full same-type batch before sending its last acknowledgement (mobile/lib/domain/services/sync_stream.service.dart#L181-L190)
A relationship backfill is treated as a normal upsert streamOlder shared assets or memberships can remain missingUse the backfill checkpoint and completion control event for each parent (server/…/sync.service.ts• L354-411)
A client continues from a stale completion pointThe server may no longer retain all audit changes needed for a safe deltaAccept SyncResetV1 and rebuild the remote projection (server/…/sync.service.ts• L263-272, mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L46-L88)
A remote delete is applied without linked local cleanupLocal albums or face records can point to missing assetsApply the delete path with its related cleanup rules (mobile/lib/infrastructure/repositories/sync_stream.repository.dart#L217-L230)
Device media permission is missing during trash reconciliationRemote trash state cannot be reflected on the deviceCheck media-management permission before changing device media (mobile/lib/domain/services/local_sync.service.dart#L48-L55, mobile/lib/domain/services/sync_stream.service.dart#L541-L558)
An external library path becomes invalid or inaccessibleFiles can be skipped or existing assets can be marked offlineValidate paths and recheck each asset against current paths and patterns (server/…/library.service.ts• L297-335, server/…/library.service.ts• L576-613)
A session is deleted while its client still tries to syncThe client loses access and cannot advance its session checkpointsInvalidate the session and let the client create or use a valid session (server/…/session.service.ts• L68-77)
An album notification job runs after its album or recipient is goneThe notification is skipped and no stale message or email is sentRecheck both records before creating the local notice or sending email (server/…/notification.service.ts• L325-343, server/…/notification.service.ts• L375-388)
Email preferences or SMTP are disabledThe durable local notice remains, but no email is sentCheck recipient preferences and SMTP configuration before queuing or sending mail (server/…/notification.service.ts• L339-343, server/…/notification.service.ts• L399-403, server/…/notification.service.ts• L431-436)

Key files

FileWhy to read it
server/…/sync.controller.tsDefines the public stream and acknowledgement endpoints.
server/…/sync.service.tsExplains stream order, reset decisions, backfill, and completion.
server/…/sync.dto.tsDefines the versioned payload shapes and event families.
server/…/sync.repository.tsShows the server's ordered, user-scoped change queries.
server/…/sync-checkpoint.table.tsDefines durable per-session progress.
mobile/lib/infrastructure/repositories/sync_api.repository.dartShows stream transport, parsing, and request capability selection.
mobile/lib/domain/services/sync_stream.service.dartShows client batching, migrations, acknowledgements, and reset handling.
mobile/lib/infrastructure/repositories/sync_stream.repository.dartShows the durable remote projection and its reset behavior.
mobile/lib/domain/services/local_sync.service.dartShows reconciliation between the app and device media store.
server/…/activity.service.tsDefines album and asset comments and likes.
server/…/notification.service.tsConnects durable notifications with live events, session and asset updates, and email jobs.
server/…/session.service.tsDefines session creation, reset flags, expiry cleanup, and invalidation.
server/…/library.service.tsDefines external library discovery, watch filtering, and its asset lifecycle.