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:
| State | Main purpose | Durable owner | Client result |
|---|---|---|---|
| Remote library state | Keep assets and their related records current | Server tables and audit records | Mobile remote-data database |
| Session progress | Record which stream changes a device has applied | Server session and checkpoint records | Resume from the last acknowledged change |
| Activity state | Store album and asset comments or likes | Server activity records | Cached activity view |
| Notification state | Store user notices and read status | Server notification records | Unread notification view |
| Device media state | Match backup albums with phone media | Device media provider and local database | Local 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:
| Family | Client-visible purpose |
|---|---|
| User and partner | Resolve owners, shared users, and partner-library access |
| Asset and asset details | Reconcile asset identity, file details, EXIF, edits, metadata, and OCR |
| Album and membership | Rebuild shared albums, member roles, and album membership |
| Album links | Keep album-to-asset and related EXIF links consistent |
| Memory and stack | Keep generated memories and grouped assets current |
| People and faces | Keep person records and face locations current |
| Control events | Mark 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
| Trigger | Consequence | Guard |
|---|---|---|
| Client acknowledges a batch before its local write completes | A restart can skip records that never reached the local store | Apply 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 stream | Older shared assets or memberships can remain missing | Use the backfill checkpoint and completion control event for each parent (server/…/sync.service.ts• L354-411) |
| A client continues from a stale completion point | The server may no longer retain all audit changes needed for a safe delta | Accept 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 cleanup | Local albums or face records can point to missing assets | Apply 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 reconciliation | Remote trash state cannot be reflected on the device | Check 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 inaccessible | Files can be skipped or existing assets can be marked offline | Validate 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 sync | The client loses access and cannot advance its session checkpoints | Invalidate 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 gone | The notification is skipped and no stale message or email is sent | Recheck 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 disabled | The durable local notice remains, but no email is sent | Check 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
| File | Why to read it |
|---|---|
| server/…/sync.controller.ts | Defines the public stream and acknowledgement endpoints. |
| server/…/sync.service.ts | Explains stream order, reset decisions, backfill, and completion. |
| server/…/sync.dto.ts | Defines the versioned payload shapes and event families. |
| server/…/sync.repository.ts | Shows the server's ordered, user-scoped change queries. |
| server/…/sync-checkpoint.table.ts | Defines durable per-session progress. |
mobile/lib/infrastructure/repositories/sync_api.repository.dart | Shows stream transport, parsing, and request capability selection. |
mobile/lib/domain/services/sync_stream.service.dart | Shows client batching, migrations, acknowledgements, and reset handling. |
mobile/lib/infrastructure/repositories/sync_stream.repository.dart | Shows the durable remote projection and its reset behavior. |
mobile/lib/domain/services/local_sync.service.dart | Shows reconciliation between the app and device media store. |
| server/…/activity.service.ts | Defines album and asset comments and likes. |
| server/…/notification.service.ts | Connects durable notifications with live events, session and asset updates, and email jobs. |
| server/…/session.service.ts | Defines session creation, reset flags, expiry cleanup, and invalidation. |
| server/…/library.service.ts | Defines external library discovery, watch filtering, and its asset lifecycle. |