🏠 Overview â€ș 🎯 Features â€ș🎯 Background Sync

Background Sync

Feature Detail

high complexity extracted Offline & Sync Confidence: 100%
6
Components
2
Shared
0
User Stories
Yes
Analyzed

Description

Background Sync is the engine that reconciles locally captured changes with the shared backend whenever connectivity is available. It maintains a mutation outbox of pending writes (new activities, edited contacts, notes), retries failed operations with exponential backoff, maps offline-generated client IDs to server IDs, and resolves conflicts when the same record was edited remotely. A Sync Status Widget surfaces current state - syncing, pending count, last successful sync, errors - so users can verify that their field work has reached the backend.

Sources & reasoning

Second canonical feature of the Offline & Sync area per §8. The Core/Shared architecture block explicitly describes mutation outbox, retry/backoff, ID mapping, and conflict resolver - all responsibilities of this feature. MVP because offline support is unsafe without reconciliation.

  • Offline-first persistence (Drift + SQLCipher encrypted local DB, mutation outbox, sync queue with retry/backoff, ID mapping for offline-created entities, conflict resolver)
  • Optimistic mutations with automatic rollback on failure (contact edits and paginated list updates)
  • offline-sync | Offline & Sync | Offline Data Support, Background Sync

Analysis

Business Value

Without reliable sync, offline support becomes a data-loss risk rather than a productivity feature. Background Sync turns the local DB into a durable buffer: peer mentors register activities in the field and trust they will appear in coordinator dashboards and Bufdir-bound aggregates without manual action. Visible sync status reduces support load by letting users self-diagnose connectivity issues, and the retry/backoff design protects backend capacity during outages. For organizations the strategic value is data completeness - every activity captured offline ultimately reaches the reporting pipeline that funds the program.

Implementation Notes

The outbox is a Drift table of pending mutations with operation type, payload, attempt count, and last error. A sync engine drains the outbox in order via the typed ApiHttpClient, honoring JWT refresh and 15s timeouts. Server-assigned IDs returned from POSTs are written back through an ID mapping layer so subsequent dependent mutations (e.g. attachment upload referencing a freshly created activity) target the correct entity. Conflict resolution uses last-write-wins by default with field-level merging for known-divergent fields. Exponential backoff caps at a few minutes to balance freshness and battery; sync also triggers on app foreground and on connectivity restore.

Quality Assurance

Peer Mentor (primary) · Coordinator (same flow)
1
Scenarios
5
UAT Steps
12
A11y Annotations
3
Role Boundaries
Peer Mentor (Likeperson)

Peer Mentor (Likeperson)

Quick UAT

  1. Sett enheten i flymodus. Logg en aktivitet via Hurtiglogg og lagre. Bekreft at Synkroniseringsstatus viser 'Venter: 1' og at aktiviteten er merket 'Ikke synkronisert' i Mine aktiviteter.
  2. UtfÞr en ny endring offline (rediger aktivitetens varighet). Bekreft at Synkroniseringsstatus nÄ viser 'Venter: 2'.
  3. SlÄ av flymodus. Bekreft at widgeten gÄr til 'Synkroniserer ...' og deretter til 'Synkronisert nÄ' med tom kÞ ('Venter: 0').
  4. Åpne aktivitetens detaljside. Bekreft at server-tildelt ID vises (ikke 'temp-...'), at varighetsendringen er bevart, og at status er 'Synkronisert'.
  5. Simuler nettverksfeil (slĂ„ pĂ„ flymodus midt i sync). Bekreft at widgeten viser 'Feil – prĂžver igjen om x sek' med eksponentiell venting, og at ingen duplikate aktiviteter dukker opp nĂ„r nettet kommer tilbake.

Quick UAT — Accessibility

  1. Sett enheten i flymodus. Logg en aktivitet via Hurtiglogg og lagre. Bekreft at Synkroniseringsstatus viser 'Venter: 1' og at aktiviteten er merket 'Ikke synkronisert' i Mine aktiviteter.
    • Screen reader VoiceOver/TalkBack annonserer 'Synkroniseringsstatus, knapp, Venter: 1 element ikke synkronisert'. Aktivitetsraden annonserer 'Ikke synkronisert' som del av tilgjengelig navn, ikke kun via ikon.
    • Focus visibility Synlig fokusring pĂ„ widgeten; status er ikke utelukkende formidlet med farge.
    • Contrast Status 'Ikke synkronisert' har tekst- eller ikon-etikett i tillegg til farge; kontrast ≄ 4.5:1.
  2. UtfÞr en ny endring offline (rediger aktivitetens varighet). Bekreft at Synkroniseringsstatus nÄ viser 'Venter: 2'.
    • Keyboard / focus Widgeten er nĂ„bar via Tab og kan aktiveres med Enter/Mellomrom for Ă„ Ă„pne detaljpanel.
    • Live region Polite live region annonserer 'SynkroniseringskĂž: 2 elementer venter'.
  3. SlÄ av flymodus. Bekreft at widgeten gÄr til 'Synkroniserer ...' og deretter til 'Synkronisert nÄ' med tom kÞ ('Venter: 0').
    • Screen reader Skjermleser kunngjĂžr tilstandsendringen uten Ă„ avbryte pĂ„gĂ„ende lesning.
    • Live region Polite live region annonserer 'Synkroniserer 2 elementer' og deretter 'Alle endringer synkronisert'.
  4. Åpne aktivitetens detaljside. Bekreft at server-tildelt ID vises (ikke 'temp-...'), at varighetsendringen er bevart, og at status er 'Synkronisert'.
    • Screen reader Detaljskjermens overskrift annonseres; statusfelt har label 'Synkroniseringsstatus: Synkronisert'.
    • Zoom Detaljskjerm er brukbar ved 200 % zoom uten horisontal scrolling av tekst.
  5. Simuler nettverksfeil (slĂ„ pĂ„ flymodus midt i sync). Bekreft at widgeten viser 'Feil – prĂžver igjen om x sek' med eksponentiell venting, og at ingen duplikate aktiviteter dukker opp nĂ„r nettet kommer tilbake.
    • Touch target Eventuell 'PrĂžv igjen'-knapp er minst 24×24 CSS-piksler.
    • Live region Assertive live region annonserer feiltilstand Ă©n gang: 'Synkronisering mislyktes. PrĂžver igjen automatisk.'
    • Contrast Feiltilstand markeres med ikon + tekst, ikke kun rĂžd farge; kontrast ≄ 4.5:1.

Role Boundaries

3 role(s) must NOT access this feature
  • Organization Administrator

    Org Admin logger ikke inn i mobilappen som Org Admin og har derfor ingen Background Sync-flate i admin-portalen; admin-portalen er online-only og har ingen synkroniseringskĂž.

  • Global Administrator

    Global Admin har ingen mobilapp-tilgang; ingen Sync Status Widget eksponeres.

  • Prospective Buyer

    Ikke autentisert bruker pÄ salgsnettsted; ingen tilgang til mobilappens synkroniseringsfunksjon.

Expected End State

Alle offline-mutasjoner i utboksen er reconciled mot REST API-et: hver post har fÄtt server-tildelt ID, midlertidige klient-IDer er mappet, konflikter er lÞst, kÞ-dybden er 0, og Sync Status Widget viser 'Synkronisert nÄ' med oppdatert siste-sync-tidsstempel. Ingen duplikate poster er opprettet ved retry.

Components (8)

User Interface (2)

ui Offline Indicator medium ui Sync Status Widget medium

Service Layer (2)

service Local DB Service medium service Sync Engine medium

Data Layer (2)

data Encrypted Local DB medium data Sync Outbox Store medium

Shared Components

These components are reused across multiple features

User Stories

No user stories have been generated for this feature yet.