geutebruck/geutebruck_app/OFFLINE_FIRST_SETUP.md

# Offline-First Architecture Setup Guide

## Overview

The Flutter app has been upgraded to use an **offline-first architecture** with local persistence using Hive. This means:

✅ **Instant UI updates** - All CRUD operations update local storage first
✅ **Offline capable** - Edit servers without network connection
✅ **Explicit sync** - Changes are synced to the server only when you press the sync button
✅ **Conflict tracking** - Unsaved changes are tracked with a dirty count indicator
✅ **Cross-platform** - Works on Web, Windows Desktop, Mobile (Hive supports all platforms)

## Setup Steps

### 1. Install Dependencies

```bash
cd C:\DEV\COPILOT\geutebruck_app
flutter pub get
```

### 2. Generate Hive Type Adapters

```bash
flutter packages pub run build_runner build --delete-conflicting-outputs
```

This generates `server_hive_model.g.dart` with the Hive type adapter.

### 3. Run the Development Server

**Option A: Using the new dev script (with hot reload):**
```bash
.\dev-run.bat
```

Then:
- Press `r` for hot reload (instant updates)
- Press `R` for hot restart
- Press `q` to quit

**Option B: Traditional way:**
```bash
flutter run -d chrome --web-port 8081
```

## Architecture Changes

### Data Flow

**Old Architecture (Direct API):**
```
UI → BLoC → Repository → API → Database
     ↓
   State
```

**New Architecture (Local-First):**
```
UI → BLoC → Repository → Local Storage (Hive)
     ↓                           ↓
   State                    Dirty Flag
                                 ↓
                          Sync Button Pressed
                                 ↓
                          Sync Service → API → Database
                                 ↓
                          Clear Dirty Flags
```

### Key Components

1. **ServerHiveModel** (`lib/data/models/server_hive_model.dart`)
   - Hive-compatible model with sync tracking
   - Fields: `isDirty`, `syncOperation`, `lastModified`

2. **ServerLocalDataSource** (`lib/data/data_sources/local/server_local_data_source.dart`)
   - Manages Hive box operations
   - Handles dirty server tracking
   - Soft deletes for sync

3. **SyncService** (`lib/data/services/sync_service.dart`)
   - Syncs dirty servers to API
   - Downloads fresh data from API
   - Conflict resolution

4. **ServerRepository** (`lib/data/repositories/server_repository_impl.dart`)
   - Local-first CRUD operations
   - Sync operations
   - Dirty count tracking

5. **ServerBloc** (`lib/presentation/blocs/server/server_bloc.dart`)
   - New events: `SyncServersEvent`, `DownloadServersEvent`, `CheckDirtyCountEvent`
   - New states: `ServerSyncing`, `ServerSyncSuccess`, `ServerDownloading`

## UI Features

### Servers Management Screen

**Sync Button (AppBar)**
- Shows red badge with dirty count
- Disabled when no changes to sync
- Tooltip shows number of unsaved changes

**Download Button (AppBar)**
- Cloud download icon
- Fetches latest data from server
- Preserves local unsaved changes

**Server Cards**
- No visual changes (existing UI)
- Operations are now instant

## User Workflow

### Creating a Server

1. Click "Add Server" button
2. Choose G-Core or GeViScope
3. Fill in the form
4. Click "Create Server"
5. ✅ Server is saved locally with `isDirty=true` and `syncOperation='create'`
6. 🔴 Sync button shows "1" badge
7. Click sync button when ready
8. ✅ Server is created on GeViServer via API
9. ✅ Dirty flag is cleared

### Editing a Server

1. Click edit icon on a server
2. Modify fields
3. Click "Update Server"
4. ✅ Server is updated locally with `isDirty=true` and `syncOperation='update'`
5. 🔴 Sync button shows dirty count
6. Click sync button when ready
7. ✅ Server is updated on GeViServer via API
8. ✅ Dirty flag is cleared

### Deleting a Server

1. Click delete icon on a server
2. Confirm deletion
3. ✅ Server is marked as deleted locally (soft delete with `syncOperation='delete'`)
4. Server disappears from list
5. 🔴 Sync button shows dirty count
6. Click sync button when ready
7. ✅ Server is deleted from GeViServer via API
8. ✅ Server record is permanently removed from local storage

### Syncing Changes

**Manual Sync:**
- Click the sync button in the AppBar
- All dirty servers are synced sequentially
- Success message shows count of synced items
- Errors are reported individually

**Download/Refresh:**
- Click the cloud download button
- Fetches all servers from API
- Replaces local data (except dirty servers)
- Dirty servers are preserved for later sync

## Development Tips

### Hot Reload

With `dev-run.bat`, you get instant feedback:
- Save a `.dart` file
- Press `r` in the terminal
- Changes appear instantly without losing app state

### Debugging Hive

**View Hive data:**
```dart
// In your code, temporarily add:
final box = await Hive.openBox<ServerHiveModel>('servers');
print('All servers: ${box.values.toList()}');
print('Dirty servers: ${box.values.where((s) => s.isDirty).toList()}');
```

**Clear all local data:**
```dart
// In your code, temporarily add:
final box = await Hive.openBox<ServerHiveModel>('servers');
await box.clear();
```

Or use the download button to replace all data from the server.

### Testing Offline Functionality

1. **Start app and load servers** (downloads from API)
2. **Disconnect network** (disable WiFi or unplug)
3. **Create/Edit/Delete servers** (works offline!)
4. **Reconnect network**
5. **Click sync button** (pushes all changes)

## Troubleshooting

### Issue: "Bad state: Type ServerHiveModelAdapter not registered"

**Solution:** Run the code generator:
```bash
flutter packages pub run build_runner build --delete-conflicting-outputs
```

### Issue: "MissingPluginException(No implementation found for method...)"

**Solution:** Restart the app completely (not hot reload):
- Stop the running app (Ctrl+C)
- Run `.\dev-run.bat` again

### Issue: Sync button not showing dirty count

**Solution:** Trigger a reload by navigating away and back, or check that the BLoC is emitting states correctly.

### Issue: "Failed to load servers"

**Cause:** No data in local storage yet

**Solution:** Click the download button to fetch servers from the API

## Performance Benefits

- **Instant operations**: Create/Update/Delete is instantaneous (no network wait)
- **Reduced API calls**: Only sync when explicitly requested
- **Better UX**: Users can edit multiple servers before syncing
- **Offline capable**: Works without internet connection
- **Reduced server load**: Batch operations instead of individual API calls

## Future Windows Desktop Port

The architecture is ready for Windows desktop:
- ✅ Hive works on Windows desktop
- ✅ All dependencies are cross-platform
- ✅ No web-specific code

When porting to Windows:
1. Add Windows as a target platform
2. Run the same code
3. Hive will use native Windows storage

## Next Steps

1. **Test the flow**:
   - Create a server
   - Edit it
   - Check dirty count
   - Sync it
   - Download from server

2. **Consider enhancements**:
   - Auto-sync on app close
   - Sync interval (e.g., every 5 minutes)
   - Conflict resolution UI (if server data changed)
   - Undo/redo for local changes

3. **Port to Windows**:
   - Add `windows` directory
   - Run `flutter run -d windows`
   - Same codebase, native Windows app

## Summary

You now have a production-ready offline-first architecture that:
- Works instantly on the client side
- Syncs explicitly to the server
- Tracks unsaved changes
- Works offline
- Ready for Windows desktop

Enjoy the speed! 🚀