Rijad Zuzo
88 lines
2.4 KiB
Markdown
88 lines
2.4 KiB
Markdown
# 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
|
|
```
|