Sync Service (Port 8003)

The sync-service manages data synchronization between ODK Collect devices and the MQUAD platform, handling conflict resolution and delta sync.

Database

Database: sync_db

Table	Purpose
`devices`	ODK device registrations

API Endpoints

All sync endpoints are prefixed with /api/v1/sync to maintain compatibility with mobile client routing.

Method	Path	Purpose
GET	`/api/v1/sync/devices`	List registered devices
POST	`/api/v1/sync/devices`	Register a new device
POST	`/api/v1/sync/pull`	Pull delta changes from server
POST	`/api/v1/sync/push`	Push idempotent changes from device
GET	`/api/v1/sync/conflicts`	List unresolved sync conflicts

Sync Flow

ODK Collect ──► Traefik (:80) ──► sync-service (:8003) ──► data-service (:8002)
                                          │
                                     conflict check
                                          │
                                    ┌─────┴─────┐
                                    │  Accept    │
                                    │  or        │
                                    │  Reject    │
                                    └───────────┘

Conflict Resolution

The sync-service detects conflicts during push operations and supports multiple strategies:

Last Write Wins (Default) — Uses the most recent updated_at timestamp.
Server Wins — Keeps the server record and rejects the client change.
Client Wins — Overwrites the server record with the client data.

Delta Sync

The service implements an efficient delta sync mechanism:

Only transfers records modified after the client's last_sync_at timestamp.
Returns a list of deleted IDs to ensure local client cleanup.
Uses a sync_token for sequential tracking of synchronization batches.