worker/docs/CART_INITIALIZATION.md

# Cart Initialization & Keep Alive Implementation

## Overview
The cart is now initialized when the app starts (on HomePage mount) and kept alive throughout the entire app session. This ensures:
- Cart data is loaded from API once on startup
- Cart state persists across all navigation
- No unnecessary re-fetching when navigating between pages
- Real-time cart badge updates across all screens

## Implementation Details

### 1. Cart Provider with Keep Alive
**File**: `lib/features/cart/presentation/providers/cart_provider.dart`

```dart
@Riverpod(keepAlive: true)  // ✅ Keep alive throughout app session
class Cart extends _$Cart {
  @override
  CartState build() {
    return CartState.initial().copyWith(
      memberTier: 'Diamond',
      memberDiscountPercent: 15.0,
    );
  }

  Future<void> initialize() async {
    // Load cart from API with Hive fallback
    // ...
  }
}

// Dependent providers also need keepAlive
@Riverpod(keepAlive: true)
int cartItemCount(Ref ref) {
  final cartState = ref.watch(cartProvider);
  return cartState.items.length;
}

@Riverpod(keepAlive: true)
double cartTotal(Ref ref) {
  final cartState = ref.watch(cartProvider);
  return cartState.total;
}
```

### 1.1 Cart Data Providers with Keep Alive
**File**: `lib/features/cart/data/providers/cart_data_providers.dart`

**CRITICAL**: All cart data layer providers must also use `keepAlive: true` to prevent disposal errors:

```dart
@Riverpod(keepAlive: true)
CartLocalDataSource cartLocalDataSource(Ref ref) {
  final hiveService = HiveService();
  return CartLocalDataSourceImpl(hiveService);
}

@Riverpod(keepAlive: true)
Future<CartRemoteDataSource> cartRemoteDataSource(Ref ref) async {
  final dioClient = await ref.watch(dioClientProvider.future);
  return CartRemoteDataSourceImpl(dioClient);
}

@Riverpod(keepAlive: true)
Future<CartRepository> cartRepository(Ref ref) async {
  final remoteDataSource = await ref.watch(cartRemoteDataSourceProvider.future);
  final localDataSource = ref.watch(cartLocalDataSourceProvider);
  return CartRepositoryImpl(
    remoteDataSource: remoteDataSource,
    localDataSource: localDataSource,
  );
}
```

**Why all providers need keepAlive:**
- Cart provider depends on cartRepository
- If repository is disposed, cart operations fail with "Ref disposed" error
- All dependencies in the chain must persist together
- Ensures consistent lifecycle management

**Benefits of `keepAlive: true`:**
- Provider state is never disposed
- Cart data persists when navigating away and back
- No re-initialization needed on subsequent visits
- Consistent cart count across all app screens
- No "Ref disposed" errors during async operations

### 2. HomePage Initialization
**File**: `lib/features/home/presentation/pages/home_page.dart`

```dart
class HomePage extends ConsumerStatefulWidget {
  const HomePage({super.key});

  @override
  ConsumerState<HomePage> createState() => _HomePageState();
}

class _HomePageState extends ConsumerState<HomePage> {
  @override
  void initState() {
    super.initState();
    // Initialize cart from API on app startup
    WidgetsBinding.instance.addPostFrameCallback((_) {
      ref.read(cartProvider.notifier).initialize();
    });
  }

  @override
  Widget build(BuildContext context) {
    // Watch cart item count for badge
    final cartItemCount = ref.watch(cartItemCountProvider);
    // ...
  }
}
```

**Why in HomePage?**
- HomePage is the first screen after login
- Ensures cart is loaded early in app lifecycle
- Provides immediate cart count for navigation badge

### 3. Cart Badge Integration
**Location**: All pages with cart icon/badge

```dart
// Any page can watch cart count - it's always available
final cartItemCount = ref.watch(cartItemCountProvider);

// Display badge
if (cartItemCount > 0)
  Badge(
    label: Text('$cartItemCount'),
    child: Icon(Icons.shopping_cart),
  )
```

## Data Flow

```
App Start
    ↓
HomePage mounts
    ↓
initState() calls cart.initialize()
    ↓
Cart loads from API → Syncs to Hive
    ↓
Cart state updates with items
    ↓
cartItemCountProvider updates
    ↓
All badges across app update reactively
    ↓
[keepAlive ensures state persists during navigation]
```

## API & Local Storage Integration

### Initialize Flow
1. **API First**: Fetch cart items from ERPNext API
2. **Product Details**: For each cart item, fetch full product data
3. **Calculate Conversions**: Apply business rules (boxes, m², etc.)
4. **Update State**: Set cart items with full product info
5. **Local Sync**: Automatically synced to Hive by repository

### Offline Fallback
- If API fails, cart loads from Hive cache
- All mutations queue for sync when online
- See `cart_repository_impl.dart` for sync logic

## Cart Operations

All cart operations work seamlessly after initialization:

```dart
// Add to cart (from any page)
await ref.read(cartProvider.notifier).addToCart(product, quantity: 2.0);

// Remove from cart
await ref.read(cartProvider.notifier).removeFromCart(productId);

// Update quantity
await ref.read(cartProvider.notifier).updateQuantity(productId, 5.0);

// Clear cart
await ref.read(cartProvider.notifier).clearCart();
```

All operations:
- Sync to API first
- Fallback to local on failure
- Queue for sync when offline
- Update UI reactively

## Testing Keep Alive

To verify keepAlive works:

1. **Navigate to HomePage** → Cart initializes
2. **Add items to cart** → Badge shows count
3. **Navigate to Products page** → Badge still shows count
4. **Navigate back to HomePage** → Cart state preserved, no re-fetch
5. **Navigate to Cart page** → Same items, no loading
6. **Hot restart app** → Cart reloads from API

## Performance Benefits

- **One-time API call**: Cart loads once on startup
- **No re-fetching**: Navigation doesn't trigger reloads
- **Instant updates**: All cart operations update state immediately
- **Offline support**: Hive cache provides instant fallback
- **Memory efficient**: Single provider instance for entire app

## Error Handling

If cart initialization fails:
- Error stored in `cartState.errorMessage`
- Can retry via `ref.read(cartProvider.notifier).initialize()`
- Cart page shows error state with retry button
- Local Hive cache used if available

## Related Files

- **Cart Provider**: `lib/features/cart/presentation/providers/cart_provider.dart`
- **Cart State**: `lib/features/cart/presentation/providers/cart_state.dart`
- **Data Providers**: `lib/features/cart/data/providers/cart_data_providers.dart`
- **Repository**: `lib/features/cart/data/repositories/cart_repository_impl.dart`
- **HomePage**: `lib/features/home/presentation/pages/home_page.dart`

## Future Enhancements

Potential improvements:
- Add periodic background sync (every 5 minutes)
- Implement optimistic updates for faster UI
- Add cart merge logic when switching accounts
- Implement cart expiry (clear after 30 days)
- Add analytics tracking for cart events