Mobile sync: end-to-end data flow

Pull path

1. The field app calls the Go sync endpoint.
2. go-sync validates the existing Laravel JWT using the shared JWT_SECRET.
3. Field-access rules enforce campaign membership, active/planning campaign state, geography scope and the device-lock policy.
4. The service performs an optimized direct pull for campaign configuration, assigned geography, stock and waybills.
5. The device stores the payload locally for offline work.

Push path

1. The device submits queued offline records with device/local identifiers.
2. go-sync records the batch in sync_ingest_batches using a tenant/user/device-scoped idempotency hash.
3. Admission is bounded. Redis uses a processing-list pattern so queued work is not lost by a simple pop.
4. Native writers apply households, children, deliveries, referrals, household interventions, stock journal entries, waybill accept/reject, stock issue/return, stock counts, field presence, training attendance and form submissions.
5. Database unique constraints, ON CONFLICT, idempotency markers and row locks prevent a retry from double-applying the transaction.
6. PostgreSQL heartbeat/status fields allow interrupted work to be recovered.

Important operational rule

A retry is normal. Never design field support around “the request will only be sent once.” The server path must remain idempotent, and support staff should not clear app storage while unsynced records remain on a device.