# Sync Service

# Sync Service (Port 8003) {#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}


**Database:** `sync_db`

| Table | Purpose |
|-------|---------|
| `devices` | ODK device registrations |


## API Endpoints {#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 {#sync-flow}


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


## Conflict Resolution {#conflict-resolution}


The sync-service detects conflicts during push operations and supports multiple strategies:
1. **Last Write Wins** (Default) — Uses the most recent `updated_at` timestamp.
2. **Server Wins** — Keeps the server record and rejects the client change.
3. **Client Wins** — Overwrites the server record with the client data.


## Delta Sync {#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.