# Sync And Backend

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

## Runtime Modes

Fake backend:

```bash
flutter run --dart-define=USE_FAKE_BACKEND=true
```

REST backend:

```bash
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:

```text
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:

```bash
flutter test test/integrations/backend
flutter test test/features/sync
```