rely/docs/SYNC_AND_BACKEND.md

Sync And Backend

The app has a backend boundary but remains local-first by default.

Runtime Modes

Fake backend:

flutter run --dart-define=USE_FAKE_BACKEND=true

REST backend:

flutter run \
  --dart-define=USE_FAKE_BACKEND=false \
  --dart-define=BACKEND_BASE_URL=https://your-api

BackendGatewayFake is the normal development path. It should stay offline-safe and must not seed relationship records into local state.

Backend Boundary

Canonical files:

• lib/integrations/backend/backend_gateway.dart
• lib/integrations/backend/backend_gateway_fake.dart
• lib/integrations/backend/backend_gateway_rest.dart
• lib/integrations/backend/backend_gateway_provider.dart
• lib/integrations/backend/models/backend_models.dart
• docs/api/openapi.yaml

The OpenAPI contract is the source for REST protocol intent. Generated Freezed files are committed and should be regenerated when backend models change.

Sync Queue

Canonical files:

• lib/features/sync/data/sync_queue_repository.dart
• lib/features/sync/application/sync_coordinator.dart
• lib/features/sync/application/sync_auto_trigger_controller.dart
• lib/features/sync/application/sync_background_runner.dart
• lib/features/sync/presentation/sync_view.dart

Local writes enqueue ChangeEnvelope objects. Push accepts or rejects them. Rejected changes can be inspected and repaired from Sync view.

Auto Sync

Background sync is disabled by default in the current local-first posture:

ENABLE_BACKGROUND_SYNC=false

When enabled, triggers include startup, resume, periodic intervals, and offline-to-online transitions. REST mode is reachability-gated.

Known Mapping Gap

Not every local entity maps to the backend protocol yet. Newer local-first entities such as facts, important dates, preference signals, shared inbox, and AI drafts may need explicit backend protocol decisions before real multi-device sync.

Do not assume adding a local model automatically syncs it.

Backend Change Checklist

1. Update docs/api/openapi.yaml.
2. Update backend DTOs in lib/integrations/backend/models/.
3. Regenerate generated models when needed.
4. Update REST gateway mapping.
5. Update fake gateway behavior.
6. Update sync envelope validation.
7. Update repository enqueue payloads.
8. Add serialization and sync coordinator tests.

Useful tests:

flutter test test/integrations/backend
flutter test test/features/sync