Production Flutter E-Commerce Architecture: Clean Layers, Offline Repository & Safe Sync

┌────────────────────────────────────────────────────────┐
│               PRESENTATION LAYER (UI)                 │
│  Widgets, Pages, Controllers/Blocs, Reactive Signals   │
└──────────────────────────┬─────────────────────────────┘
                           │ uses (interfaces only)
┌──────────────────────────▼─────────────────────────────┐
│                 DOMAIN LAYER (PURE DART)               │
│  Entities, Value Objects, Use Cases, Repositories API  │
└──────────────────────────▲─────────────────────────────┘
                           │ implements
┌──────────────────────────┴─────────────────────────────┐
│                  DATA LAYER (INFRA)                    │
│  Local SQLite Cache, Remote REST/GraphQL, Network Mon. │
└────────────────────────────────────────────────────────┘

import 'package:meta/meta.dart';
@immutable
class Money {
  final int amountInCents;
  final String currencyCode;
  const Money(this.amountInCents, {this.currencyCode = 'USD'});
  Money operator +(Money other) {
    assert(currencyCode == other.currencyCode, 'Cannot add different currencies');
    return Money(amountInCents + other.amountInCents, currencyCode: currencyCode);
  }
  Money operator *(int factor) => Money(amountInCents * factor, currencyCode: currencyCode);
  double get asDouble => amountInCents / 100.0;
  String get formatted => '${currencyCode == 'USD' ? '$' : ''}${asDouble.toStringAsFixed(2)}';
  @override
  bool operator ==(Object other) =>
      identical(this, other) ||
      other is Money && amountInCents == other.amountInCents && currencyCode == other.currencyCode;
  @override
  int get hashCode => amountInCents.hashCode ^ currencyCode.hashCode;
}

abstract class CartRepository {
  Stream<CartSnapshot> watchCart();
  Future<CartSnapshot> getCart();
  Future<void> addItem(String productId, int quantity);
  Future<void> updateQuantity(String productId, int quantity);
  Future<void> removeItem(String productId);
  Future<SyncResult> synchronizeWithServer();
}

import 'dart:async';
import 'package:flutter/foundation.dart';
class CartLine {
  final String id;
  final String title;
  final Money unitPrice;
  final int quantity;
  final int maxStock;
  const CartLine({
    required this.id,
    required this.title,
    required this.unitPrice,
    required this.quantity,
    required this.maxStock,
  });
  Money get lineTotal => unitPrice * quantity;
  CartLine copyWith({int? quantity}) => CartLine(
    id: id,
    title: title,
    unitPrice: unitPrice,
    quantity: quantity ?? this.quantity,
    maxStock: maxStock,
  );
}
class CartState {
  final List<CartLine> items;
  final bool isSyncing;
  final String? syncError;
  const CartState({
    required this.items,
    this.isSyncing = false,
    this.syncError,
  });
  Money get subtotal => items.fold(
    const Money(0),
    (sum, item) => sum + item.lineTotal,
  );
  int get totalItemCount => items.fold(0, (count, item) => count + item.quantity);
}
class ProductionCartNotifier extends ValueNotifier<CartState> {
  final Future<void> Function(List<CartLine>) onRemoteSync;
  ProductionCartNotifier({required this.onRemoteSync})
      : super(const CartState(items: []));
  /// Optimistic quantity update with boundary clamping
  Future<void> updateItemQuantity(String id, int newQuantity) async {
    final oldItems = value.items;
    final index = oldItems.indexWhere((it) => it.id == id);
    if (index == -1) return;
    final targetItem = oldItems[index];
    final clampedQty = newQuantity.clamp(0, targetItem.maxStock);
    List<CartLine> updatedItems;
    if (clampedQty == 0) {
      updatedItems = List.of(oldItems)..removeAt(index);
    } else {
      updatedItems = List.of(oldItems)..[index] = targetItem.copyWith(quantity: clampedQty);
    }
    // 1. Optimistic local update
    value = CartState(items: updatedItems, isSyncing: true);
    // 2. Debounced or immediate remote sync
    try {
      await onRemoteSync(updatedItems);
      value = CartState(items: updatedItems, isSyncing: false);
    } catch (e) {
      // 3. Rollback on hard error and notify UI
      value = CartState(
        items: oldItems,
        isSyncing: false,
        syncError: 'Failed to update cart: ${e.toString()}',
      );
    }
  }
}