Offline sync design

The delegate app works offline-first (ADR-010): cahier §7.3 requires it to keep « une tournée, des visites, notes et photos en cas de réseau faible », with a sync queue that handles « les reprises, doublons, erreurs et conflits » and a visible state synchronisé, en attente or en erreur (SYN-03–SYN-06). This page is the server side: how the API makes replay safe, how it detects and reports conflicts, and how it feeds the device with changes.

• The contract — request and response shapes, result classes, examples — is on Offline sync & location (sync.batch, sync.delta, sync.locationPings).
• The client side — local database, outbox states, retry scheduler, sync centre UX — is on mobile offline sync.
• Built in SRV-23 (server) and MOB-09 (client); proven in the field test MOB-13.

PrinciplesCopy Anchor Link

1. One implementation per action. A replayed item runs exactly the procedure the direct call runs — same permission and scope checks, validation, guards, transaction and events. The batch is a dispatcher, never a second code path.
2. The key is born with the action. The app assigns the Idempotency-Key when the delegate taps, not when it sends; the direct attempt and every replay share it, so a lost response never duplicates anything.
3. Two times, both kept. occurredAt is when the delegate acted (device clock, corrected by the server offset); receivedAt is when the server got it. Business facts use occurredAt; plausibility bounds it.
4. Records born offline have client ids. The server upserts on them, so a creation replayed after a lost response is a no-op.
5. The server's verdict is final, judged fairly. State, scope and ownership are evaluated at execution time; policy settings (GPS tolerance, mandatory report…) as they were at occurredAt (policy rules versus invariants).
6. No silent resolution. The server never merges or overwrites to make a conflict disappear. It reports CONFLICT with the current server state, and the delegate decides in the sync centre (DA-27).

What works offlineCopy Anchor Link

Decided per operation on the delegate API pages; summarised here with the reason.

Client-generated idsCopy Anchor Link

Records that can be created offline carry a UUIDv7 generated by the app: Reseller (field prospects), Visit (unplanned), VisitPhoto, VisitReport, Interaction (notes), ResellerPhoto and their File rows (database design).

Client ids are identifiers, never credentials: every operation still checks that the caller may act on the parent record. When a creation fails (for example a duplicate phone), the id stays free, so the corrected creation can reuse it and the queued actions that point to it stay valid.

IdempotencyCopy Anchor Link

The server-wide rules are on Architecture and data; what matters for offline replay:

• Scope and fingerprint. IdempotencyRecord is unique on (scopeKey = user:<userId>, key) and stores the fingerprint of method + path + body (model). A direct call and a batch item with the same key are the same action.
• The batch has its own key for the batch content. Retrying the exact same batch returns the whole stored response; any change of the items needs a new batch key, and items already processed then answer from their own records (REPLAYED, or the stored refusal with replayed: true).
• Stored outcomes. Successes and business refusals are stored for 30 days; transient outcomes (5xx, 401, 429, IDEMPOTENCY_IN_PROGRESS) are not, so the same key retries.
• Coalescing on the device. Checklist, note and report saves of a visit are coalesced while they have never been sent: the outbox keeps only the latest body under the newest key. An item that has been sent once — even if its response was lost — is frozen: its body never changes, or the next replay would be IDEMPOTENCY_KEY_REUSED.
• Concurrency. Batches of the same user are serialised by a Redis lock sync:user:<userId> (wait up to 5 s), so two devices or an overlapping retry never interleave. A direct call still in flight with an item's key makes that item RETRY (IDEMPOTENCY_IN_PROGRESS).

Time: occurredAt and receivedAtCopy Anchor Link

Policy rules versus invariantsCopy Anchor Link

A replayed action is judged by two kinds of rules, and the difference is what keeps offline work fair without making the server lenient.

How "as in force at occurredAt" is computed:

• Settings. settings.valueAt(key, instant) reads the value valid at that instant from the setting's change history (every admin.settings.update is audited with before and after).
• Visit type and checklist template. Frozen on the visit at check-in.
• Reference position. The store position used for the tolerance is the one valid at occurredAt (position changes are in the reseller's history).

The app evaluated the same rule with its snapshot, so in the normal case both verdicts agree. What this prevents is a setting published while the delegate was offline — tolerance tightened from 150 m to 100 m at 10:00 — turning a 120 m check-in made at 09:40 into a refusal. A check-in that was out of tolerance even under the rules of the moment is refused (422 GPS_OUT_OF_TOLERANCE), as cahier §6.3 requires.

Batch replayCopy Anchor Link

POST /v1/sync/batch — contract on sync.batch. Inside the server:

A transient failure of one item does not abort the batch: each item is its own transaction, and items that depend on it come back DEPENDENCY_PENDING. If the database itself is unreachable, the whole request fails (500/503) and the app retries the batch with the same key.

How the app chains items (so that dependency rules do their job): each visit action depends on the previous queued action of the same visit; an unplanned visit or a note on a prospect created offline depends on its creation; a visit end depends on the photo attachments the visit type requires; markShared depends on nothing (the invitation was created online).

Normal replayCopy Anchor Link

Idempotent replay after a timeoutCopy Anchor Link

ConflictCopy Anchor Link

Conflict catalogueCopy Anchor Link

What can go wrong between the moment the delegate acts offline and the moment the server sees it. "Dependents" are the queued items that declared the conflicted item in dependsOn; they come back REJECTED / 424 DEPENDENCY_FAILED and are resolved together with it.

Proposal (not in the V1 contract): a grace period for reassignments. Scope is evaluated at execution time, so notes and photos taken on a store just before it was reassigned are refused. Accepting append-only facts whose occurredAt precedes the reassignment (from ResellerAssignment), within the 72-hour window, would keep that history. To decide with HOCO if the pilot shows the case matters.

Delta feedCopy Anchor Link

GET /v1/sync/delta — contract on sync.delta: six scopes (tours, visits, resellers, tasks, referenceLists, announcements), changes in their latest state, tombstones, nextCursor, hasMore, fullResyncRequired, serverTime.

ScopesCopy Anchor Link

The same scope resolvers as the online operations (the access module) — one definition of "what this delegate may see".

CursorCopy Anchor Link

The cursor is opaque to the app: base64url JSON signed with HMAC-SHA-256 (SYNC_CURSOR_SECRET). It holds:

Detecting changesCopy Anchor Link

Per scope, the server selects the rows of the membership with (updatedAt, id) > watermark, ordered by (updatedAt, id) — the monotonic change sequence of the contract — in one REPEATABLE READ transaction, so every page is a consistent snapshot. Each record appears once, in its latest state.

Settle window. A transaction can commit after rows with a later updatedAt were already served. To never miss it, the final cursor of a pull (when hasMore is false) is set back to now − 30 s for every scope. The next pull re-reads that short window, and the app ignores records whose version or updatedAt it already has. Transactions are bounded at 10 s (transactions), so 30 s is a safe margin. Pages within one pull use the exact keyset, without the overlap.

Two invariants keep the watermark sufficient:

1. A record that enters a scope always gets a new updatedAt (assignment, tour planning, task reassignment write the row) — except through time windows, which the server handles from the anchor: tours whose date enters the window (anchor + 30 to today + 30) are delivered whatever their updatedAt.
2. A visit never changes tour: moving a stop means cancelling it in one tour and creating a new visit in the other.

TombstonesCopy Anchor Link

There is no tombstone table: records are never deleted (database design), and every way out of a scope is already recorded somewhere. The server derives tombstones since the watermarks:

Cancelled visits, deactivated reference items and archived templates are not tombstones: they come back as changes with their status (CANCELLED, active: false), because the device needs to show them.

Paging and full resyncCopy Anchor Link

• Paging. Up to limit records per page across scopes (default 500, maximum 1 000), scopes served in a fixed order — referenceLists, tours, visits, resellers, tasks, announcements — so parents arrive before children. hasMore = true until the backlog is drained; the app applies each page in one local transaction and loops at once.
• fullResyncRequired when the cursor is older than 7 days, the format version changed, or the zone digest no longer matches. The app reloads every scope without a cursor and swaps the cached data only once the reload completes, so the app stays usable offline mid-resync. It never drops its outbox, and replays it afterwards.
• The today snapshot (delegate.tours.today) returns a deltaCursor taken in the same database snapshot as its payload.

Sync hintsCopy Anchor Link

When the back-office changes something in a delegate's scope, the sync module's handlers (on tour.updated, tour.cancelled, tour.reopened, visit.added, visit.unlocked, reseller.assigned, task.assigned, delegate.zones_changed, announcement.published, field-policy settings.changed) ask notifications for a silent push (data message { "type": "SYNC" }, collapse key sync, at most one per delegate per minute). The app pulls the delta within seconds when online. An app in the foreground also sees notification.created on its live stream (events.stream).

Indexes that keep pulls cheap: (delegateId, updatedAt) on tours; (tourId, updatedAt) on visits; (assigneeId, updatedAt) on tasks; (fromDelegateId, createdAt) on assignments; (entityType, createdAt) on the audit log.

Photos offlineCopy Anchor Link

Uploaded but never attached files are purged after 7 days and pending uploads after 24 hours — longer than the 72-hour offline window for the first, while a pending upload is re-created on the next attempt anyway.

Location pingsCopy Anchor Link

sync.locationPings, outside the batch because it is high-volume, append-only and loss-tolerant.

SecurityCopy Anchor Link

• Same authorisation as online. Every item runs the direct operation's permission and scope checks with the scope at execution time; a record that left the scope is a conflict, never applied.
• Session expiry or revocation while offline. The batch answers 401; the app keeps its outbox untouched, asks the delegate to sign in, and resumes with the same keys. Sessions last 30 days sliding, longer than the 72-hour window of replayable actions.
• One outbox per user. The app partitions its outbox by user: if another person signs in on the device, the previous user's queue stays encrypted on the device and is not replayed until that user signs in again. Idempotency scope user:<userId> would otherwise apply the actions under the wrong identity. Proposal: add an ownerUserId field to SyncBatchRequest so the server refuses a mismatch (403 SYNC_OWNER_MISMATCH) as a second line of defence.
• Traceability. Every applied item is audited like a direct call (actorApp = DELEGATE_APP, user, device id, occurredAt, receipt time, the batch's request id).
• Limits. 50 items and 1 MB per batch; 200 pings per chunk; per-user rate limits; cursors signed and bound to the user; the delta never returns data outside the current scope — tombstones carry ids only.
• Data at rest on the device (encrypted local database, outbox and photos) is specified on the mobile side.

ObservabilityCopy Anchor Link

The back-office shows each delegate's last sync time and pending-item count reported by the closing preview (delegates list BO-16, tour live detail BO-23), so a supervisor sees who has not synced. Logs carry the batch's requestId and each item's key, so a delegate's support call can be traced item by item.

Test scenariosCopy Anchor Link

Automated against a real PostgreSQL and Redis, plus the field test of MOB-13 (airplane-mode visits, sync recovery, photo queue, battery).