supplements/WEBDAV_SYNC_IMPLEMENTATION.md

# WebDAV Cloud Sync Implementation

## Overview

This document describes the WebDAV cloud sync implementation for the Supplements Tracker Flutter app. The implementation allows users to synchronize their supplement data across multiple devices using WebDAV-compatible servers like Nextcloud, ownCloud, or any standard WebDAV server.

## Architecture

### Core Components

#### 1. Data Models Enhanced with Sync Metadata

All core data models (`Supplement`, `SupplementIntake`, `Ingredient`) have been enhanced with sync metadata:

- `syncId: String` - Unique identifier for sync operations (UUID)
- `lastModified: DateTime` - Timestamp of last modification
- `syncStatus: SyncStatus` - Current sync state (pending, synced, modified, conflict, etc.)
- `isDeleted: bool` - Soft delete flag for sync purposes

#### 2. Sync Enumerations (`lib/models/sync_enums.dart`)

- `SyncStatus` - Track individual record sync states
- `SyncOperationStatus` - Overall sync operation states
- `ConflictResolutionStrategy` - How to handle conflicts
- `SyncFrequency` - Auto-sync timing options
- `ConflictType` - Types of sync conflicts

#### 3. Sync Data Models (`lib/models/sync_data.dart`)

- `SyncData` - Complete data structure for WebDAV JSON format
- `SyncConflict` - Represents conflicts between local and remote data
- `SyncResult` - Results and statistics from sync operations
- `SyncStatistics` - Detailed sync operation metrics

#### 4. WebDAV Sync Service (`lib/services/webdav_sync_service.dart`)

Core service handling WebDAV communication:
- Server configuration and authentication
- Data upload/download operations
- Conflict detection and basic resolution
- Network connectivity checking
- Device identification

#### 5. Sync Provider (`lib/providers/sync_provider.dart`)

State management layer for sync operations:
- Manages sync status and progress
- Handles user configuration
- Coordinates between WebDAV service and UI
- Manages conflict resolution workflow

#### 6. UI Components

- `SyncSettingsScreen` - Complete WebDAV configuration interface
- Integration with existing settings screen
- Real-time sync status indicators
- Conflict resolution dialogs

### Database Schema Changes

The database has been upgraded to version 6 with sync support:

```sql
-- New sync columns added to existing tables
ALTER TABLE supplements ADD COLUMN syncId TEXT NOT NULL UNIQUE;
ALTER TABLE supplements ADD COLUMN lastModified TEXT NOT NULL;
ALTER TABLE supplements ADD COLUMN syncStatus TEXT NOT NULL DEFAULT 'pending';
ALTER TABLE supplements ADD COLUMN isDeleted INTEGER NOT NULL DEFAULT 0;

-- Similar columns added to supplement_intakes table

-- New sync metadata table
CREATE TABLE sync_metadata (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  key TEXT NOT NULL UNIQUE,
  value TEXT NOT NULL,
  lastUpdated TEXT NOT NULL
);

-- Device info table for multi-device conflict resolution
CREATE TABLE device_info (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  deviceId TEXT NOT NULL UNIQUE,
  deviceName TEXT NOT NULL,
  lastSyncTime TEXT,
  createdAt TEXT NOT NULL
);
```

## Sync Process Flow

### 1. Configuration Phase
1. User enters WebDAV server URL, username, and password/app password
2. System tests connection and validates credentials
3. Creates sync directory on server if needed
4. Stores encrypted credentials locally using `flutter_secure_storage`

### 2. Sync Operation
1. Check network connectivity
2. Download remote sync data (JSON file from WebDAV)
3. Compare with local data using timestamps and sync IDs
4. Detect conflicts (modification, deletion, creation conflicts)
5. Merge data according to conflict resolution strategy
6. Upload merged data back to server
7. Update local sync status

### 3. Conflict Resolution
- **Last-write-wins**: Prefer most recently modified record
- **Prefer Local**: Always keep local changes
- **Prefer Remote**: Always keep remote changes
- **Manual**: Present conflicts to user for individual resolution

## Security Considerations

### Data Protection
- Credentials stored using `flutter_secure_storage` with platform encryption
- Support for app passwords instead of main account passwords
- No sensitive data logged in release builds

### Network Security
- HTTPS enforced for WebDAV connections
- Connection testing before storing credentials
- Proper error handling for authentication failures

## Supported WebDAV Servers

### Tested Compatibility
- **Nextcloud** - Full compatibility with automatic path detection
- **ownCloud** - Full compatibility with automatic path detection
- **Generic WebDAV** - Manual path configuration required

### Server Requirements
- WebDAV protocol support
- File read/write permissions
- Directory creation permissions
- Basic or digest authentication

## Data Synchronization Format

### JSON Structure
```json
{
  "version": 1,
  "deviceId": "device_12345_67890",
  "deviceName": "John's Phone",
  "syncTimestamp": "2024-01-15T10:30:00.000Z",
  "supplements": [
    {
      "syncId": "uuid-supplement-1",
      "name": "Vitamin D3",
      "ingredients": [...],
      "lastModified": "2024-01-15T09:15:00.000Z",
      "syncStatus": "synced",
      "isDeleted": false,
      // ... other supplement fields
    }
  ],
  "intakes": [
    {
      "syncId": "uuid-intake-1",
      "supplementId": 1,
      "takenAt": "2024-01-15T08:00:00.000Z",
      "lastModified": "2024-01-15T08:00:30.000Z",
      "syncStatus": "synced",
      "isDeleted": false,
      // ... other intake fields
    }
  ],
  "metadata": {
    "totalSupplements": 5,
    "totalIntakes": 150
  }
}
```

## Usage Instructions

### Initial Setup
1. Navigate to Settings → Cloud Sync
2. Enter your WebDAV server details:
   - Server URL (e.g., `https://cloud.example.com`)
   - Username
   - Password or app password
   - Optional device name
3. Test connection
4. Configure sync preferences

### Sync Options
- **Manual Sync**: Sync on demand via button press
- **Auto Sync**: Automatic background sync at configured intervals
  - Every 15 minutes
  - Hourly
  - Every 6 hours
  - Daily

### Conflict Resolution
- Configure preferred resolution strategy in settings
- Review individual conflicts when they occur
- Auto-resolve based on chosen strategy

## Implementation Status

### ✅ Completed (Phase 1)
- Core sync architecture and data models
- WebDAV service implementation
- Database schema with sync support
- Basic UI for configuration and management
- Manual sync operations
- Conflict detection
- Secure credential storage

### 🔄 Future Enhancements (Phase 2+)
- Background sync scheduling
- Advanced conflict resolution UI
- Sync history and logs
- Client-side encryption option
- Multiple server support
- Bandwidth optimization
- Offline queue management

## Dependencies Added

```yaml
dependencies:
  webdav_client: ^1.2.2      # WebDAV protocol client
  connectivity_plus: ^6.0.5   # Network connectivity checking
  flutter_secure_storage: ^9.2.2  # Secure credential storage
  uuid: ^4.5.0               # UUID generation for sync IDs
  crypto: ^3.0.5             # Data integrity verification
```

## File Structure

```
lib/
├── models/
│   ├── sync_enums.dart           # Sync-related enumerations
│   ├── sync_data.dart            # Sync data models
│   ├── supplement.dart           # Enhanced with sync metadata
│   ├── supplement_intake.dart    # Enhanced with sync metadata
│   └── ingredient.dart           # Enhanced with sync metadata
├── services/
│   ├── webdav_sync_service.dart  # WebDAV communication
│   └── database_helper.dart      # Enhanced with sync methods
├── providers/
│   └── sync_provider.dart        # Sync state management
└── screens/
    └── sync_settings_screen.dart # Sync configuration UI
```

## Error Handling

The implementation includes comprehensive error handling for:
- Network connectivity issues
- Authentication failures
- Server unavailability
- Malformed sync data
- Storage permission issues
- Conflicting concurrent modifications

## Testing Recommendations

### Unit Tests
- Sync data serialization/deserialization
- Conflict detection algorithms
- Merge logic validation

### Integration Tests
- WebDAV server communication
- Database sync operations
- Cross-device sync scenarios

### User Testing
- Multi-device sync workflows
- Network interruption recovery
- Large dataset synchronization
- Conflict resolution user experience

## Performance Considerations

- Incremental sync (only changed data)
- Compression for large datasets
- Connection timeout handling
- Memory-efficient JSON processing
- Background processing for large operations

This implementation provides a solid foundation for cloud synchronization while maintaining data integrity and user experience across multiple devices.