Retrospective: 2 Years of Using Flutter 3.x – 50K Users Analyzed with Firebase 10.0

// Import required Firebase 10.0 and utility packages
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_firestore/firebase_firestore.dart';
import 'package:connectivity_plus/connectivity_plus.dart';
import 'dart:async';

/// Production-grade Firestore service for Flutter 3.x apps using Firebase 10.0
/// Implements retry logic, network-aware caching, and structured error handling
class FirestoreService {
  final FirebaseFirestore _firestore;
  final Connectivity _connectivity;
  final _userCache = >{};
  StreamSubscription? _connectivitySubscription;
  bool _isOnline = true;

  /// Initialize service with default Firebase instance and connectivity monitor
  FirestoreService({
    FirebaseFirestore? firestore,
    Connectivity? connectivity,
  })  : _firestore = firestore ?? FirebaseFirestore.instance,
        _connectivity = connectivity ?? Connectivity() {
    // Monitor network state changes for offline-first caching
    _connectivitySubscription = _connectivity.onConnectivityChanged.listen((result) {
      _isOnline = result != ConnectivityResult.none;
      if (_isOnline) _syncCachedWrites();
    });
  }

  /// Fetch user profile from Firestore with 3 retries on transient errors
  /// Returns cached data immediately if available and offline
  Future> fetchUserProfile(String userId) async {
    // Return cached data if offline and cache has entry
    if (!_isOnline && _userCache.containsKey(userId)) {
      return _userCache[userId]!;
    }

    int retryCount = 0;
    while (retryCount < 3) {
      try {
        final doc = await _firestore.collection('users').doc(userId).get();
        if (!doc.exists) {
          throw FirebaseException(
            plugin: 'firestore',
            code: 'not-found',
            message: 'User $userId not found',
          );
        }
        final data = doc.data()!;
        // Update cache with fresh data
        _userCache[userId] = data;
        return data;
      } on FirebaseException catch (e) {
        // Retry only on transient network or unavailable errors
        if (e.code == 'unavailable' || e.code == 'deadline-exceeded') {
          retryCount++;
          if (retryCount >= 3) rethrow;
          await Future.delayed(Duration(milliseconds: 500 * retryCount));
          continue;
        }
        // Rethrow non-retryable errors immediately
        rethrow;
      } catch (e) {
        // Wrap unexpected errors in structured Firebase exception
        throw FirebaseException(
          plugin: 'firestore',
          code: 'unknown',
          message: 'Unexpected error fetching user: $e',
        );
      }
    }
    throw FirebaseException(
      plugin: 'firestore',
      code: 'retry-exhausted',
      message: 'Failed to fetch user after 3 retries',
    );
  }

  /// Sync cached writes to Firestore when network reconnects
  Future _syncCachedWrites() async {
    // Implementation omitted for brevity, but would batch pending writes
    // from a local queue to Firestore once online
  }

  /// Handle Firestore-specific errors and map to user-friendly messages
  String _handleFirestoreError(FirebaseException e) {
    switch (e.code) {
      case 'not-found':
        return 'The requested resource does not exist.';
      case 'permission-denied':
        return 'You do not have permission to access this resource.';
      case 'unavailable':
        return 'Network is currently unavailable. Please try again.';
      default:
        return 'An unexpected error occurred: ${e.message}';
    }
  }

  /// Dispose connectivity subscription to prevent memory leaks
  void dispose() {
    _connectivitySubscription?.cancel();
  }
}

// Import Flutter material and state management packages
import 'package:flutter/material.dart';
import 'package:pull_to_refresh/pull_to_refresh.dart';
import 'firestore_service.dart'; // Assumes FirestoreService from Code Example 1

/// High-performance user list widget optimized for Impeller renderer (Flutter 3.16+)
/// Implements error boundaries, skeleton loading, and pull-to-refresh
class UserListScreen extends StatefulWidget {
  final FirestoreService firestoreService;

  const UserListScreen({super.key, required this.firestoreService});

  @override
  State createState() => _UserListScreenState();
}

class _UserListScreenState extends State {
  final _refreshController = RefreshController(initialRefresh: false);
  final _users = >[];
  final _error = ValueNotifier(null);
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _loadInitialUsers();
  }

  /// Load first 50 users from Firestore with error handling
  Future _loadInitialUsers() async {
    setState(() => _isLoading = true);
    _error.value = null;
    try {
      // Query Firestore for active users sorted by last login
      final query = await widget.firestoreService._firestore
          .collection('users')
          .where('isActive', isEqualTo: true)
          .orderBy('lastLoginAt', descending: true)
          .limit(50)
          .get();
      _users.clear();
      _users.addAll(query.docs.map((doc) => doc.data()));
    } on FirebaseException catch (e) {
      _error.value = widget.firestoreService._handleFirestoreError(e);
    } catch (e) {
      _error.value = 'Failed to load users: $e';
    } finally {
      setState(() => _isLoading = false);
    }
  }

  /// Load next 50 users for pagination
  Future _loadMoreUsers() async {
    try {
      final lastUser = _users.last;
      final query = await widget.firestoreService._firestore
          .collection('users')
          .where('isActive', isEqualTo: true)
          .orderBy('lastLoginAt', descending: true)
          .startAfter([lastUser['lastLoginAt']])
          .limit(50)
          .get();
      if (query.docs.isEmpty) {
        _refreshController.loadNoData();
        return;
      }
      _users.addAll(query.docs.map((doc) => doc.data()));
      setState(() {});
      _refreshController.loadComplete();
    } on FirebaseException catch (e) {
      _error.value = widget.firestoreService._handleFirestoreError(e);
      _refreshController.loadFailed();
    } catch (e) {
      _error.value = 'Failed to load more users: $e';
      _refreshController.loadFailed();
    }
  }

  /// Build skeleton loading state for 5 items
  Widget _buildSkeletonLoader() {
    return ListView.builder(
      itemCount: 5,
      itemBuilder: (context, index) => Padding(
        padding: const EdgeInsets.all(16.0),
        child: Row(
          children: [
            Container(
              width: 48,
              height: 48,
              decoration: BoxDecoration(
                color: Colors.grey[300],
                borderRadius: BorderRadius.circular(24),
              ),
            ),
            const SizedBox(width: 16),
            Expanded(
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Container(
                    width: double.infinity,
                    height: 16,
                    color: Colors.grey[300],
                  ),
                  const SizedBox(height: 8),
                  Container(
                    width: 150,
                    height: 12,
                    color: Colors.grey[300],
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Active Users')),
      body: ValueListenableBuilder(
        valueListenable: _error,
        builder: (context, error, _) {
          if (error != null) {
            return Center(
              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  const Icon(Icons.error, size: 48, color: Colors.red),
                  const SizedBox(height: 16),
                  Text(error),
                  const SizedBox(height: 16),
                  ElevatedButton(
                    onPressed: _loadInitialUsers,
                    child: const Text('Retry'),
                  ),
                ],
              ),
            );
          }
          if (_isLoading) return _buildSkeletonLoader();
          return SmartRefresher(
            controller: _refreshController,
            enablePullDown: true,
            enablePullUp: true,
            onRefresh: () async {
              await _loadInitialUsers();
              _refreshController.refreshCompleted();
            },
            onLoading: _loadMoreUsers,
            child: ListView.builder(
              itemCount: _users.length,
              itemBuilder: (context, index) {
                final user = _users[index];
                return ListTile(
                  leading: CircleAvatar(
                    backgroundImage: NetworkImage(user['avatarUrl'] ?? ''),
                    onBackgroundImageError: (_, __) => const Icon(Icons.person),
                  ),
                  title: Text(user['displayName'] ?? 'Unknown'),
                  subtitle: Text('Last login: ${user['lastLoginAt'].toDate()}'),
                );
              },
            ),
          );
        },
      ),
    );
  }

  @override
  void dispose() {
    _refreshController.dispose();
    super.dispose();
  }
}

// Import testing and mocking packages for Flutter 3.x
import 'package:flutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:firebase_firestore/firebase_firestore.dart';
import 'package:connectivity_plus/connectivity_plus.dart';
import 'firestore_service.dart';

// Mock classes for Firebase and connectivity dependencies
class MockFirebaseFirestore extends Mock implements FirebaseFirestore {}
class MockCollectionReference extends Mock implements CollectionReference> {}
class MockDocumentReference extends Mock implements DocumentReference> {}
class MockDocumentSnapshot extends Mock implements DocumentSnapshot> {}
class MockConnectivity extends Mock implements Connectivity {}
class MockStreamSubscription extends Mock implements StreamSubscription {}

void main() {
  late FirestoreService firestoreService;
  late MockFirebaseFirestore mockFirestore;
  late MockConnectivity mockConnectivity;
  late MockStreamSubscription mockSubscription;

  // Register fallback values for mocktail
  setUpAll(() {
    registerFallbackValue(ConnectivityResult.wifi);
    registerFallbackValue(MockDocumentSnapshot());
  });

  setUp(() {
    mockFirestore = MockFirebaseFirestore();
    mockConnectivity = MockConnectivity();
    mockSubscription = MockStreamSubscription();
    firestoreService = FirestoreService(
      firestore: mockFirestore,
      connectivity: mockConnectivity,
    );

    // Stub connectivity to return online by default
    when(() => mockConnectivity.onConnectivityChanged)
        .thenAnswer((_) => Stream.value(ConnectivityResult.wifi));
  });

  tearDown(() {
    firestoreService.dispose();
    reset(mockFirestore);
    reset(mockConnectivity);
  });

  group('fetchUserProfile', () {
    const testUserId = 'test-user-123';
    final testUserData = {
      'displayName': 'John Doe',
      'email': 'john@example.com',
      'lastLoginAt': Timestamp.now(),
    };

    test('returns user data on successful Firestore fetch', () async {
      // Arrange: stub Firestore to return valid user doc
      final mockCollection = MockCollectionReference();
      final mockDoc = MockDocumentReference();
      final mockSnapshot = MockDocumentSnapshot();

      when(() => mockFirestore.collection('users')).thenReturn(mockCollection);
      when(() => mockCollection.doc(testUserId)).thenReturn(mockDoc);
      when(() => mockDoc.get()).thenAnswer((_) async => mockSnapshot);
      when(() => mockSnapshot.exists).thenReturn(true);
      when(() => mockSnapshot.data()).thenReturn(testUserData);

      // Act
      final result = await firestoreService.fetchUserProfile(testUserId);

      // Assert
      expect(result, equals(testUserData));
      verify(() => mockDoc.get()).called(1);
    });

    test('retries 3 times on unavailable Firestore error', () async {
      // Arrange: stub Firestore to throw unavailable error 3 times then succeed
      final mockCollection = MockCollectionReference();
      final mockDoc = MockDocumentReference();
      final mockSnapshot = MockDocumentSnapshot();

      when(() => mockFirestore.collection('users')).thenReturn(mockCollection);
      when(() => mockCollection.doc(testUserId)).thenReturn(mockDoc);
      when(() => mockDoc.get())
          .thenThrow(FirebaseException(plugin: 'firestore', code: 'unavailable'))
          .thenThrow(FirebaseException(plugin: 'firestore', code: 'unavailable'))
          .thenThrow(FirebaseException(plugin: 'firestore', code: 'unavailable'));

      // Act & Assert: should throw after 3 retries
      expect(
        () => firestoreService.fetchUserProfile(testUserId),
        throwsA(isA().having((e) => e.code, 'code', 'retry-exhausted')),
      );
      verify(() => mockDoc.get()).called(3);
    });

    test('returns cached data when offline', () async {
      // Arrange: set connectivity to offline
      when(() => mockConnectivity.onConnectivityChanged)
          .thenAnswer((_) => Stream.value(ConnectivityResult.none));
      // Pre-populate cache
      firestoreService._userCache[testUserId] = testUserData;

      // Act
      final result = await firestoreService.fetchUserProfile(testUserId);

      // Assert: no Firestore call made
      expect(result, equals(testUserData));
      verifyNever(() => mockFirestore.collection(any));
    });
  });

  group('dispose', () {
    test('cancels connectivity subscription', () async {
      // Arrange: stub subscription cancel
      when(() => mockSubscription.cancel()).thenAnswer((_) async {});
      // Manually set subscription for testing (using reflection or modify FirestoreService to expose)
      // Note: In production, use dependency injection to expose subscription for testing
      // This test assumes we modified FirestoreService to accept a subscription for testing
      firestoreService.dispose();
      verifyNever(() => mockSubscription.cancel()); // Adjust based on actual implementation
    });
  });
}

// Initialize Firebase with flavor-specific config
Future initializeFirebase() async {
  final flavor = F.flavor; // Generated by flutter_flavorizr
  FirebaseOptions options;
  switch (flavor) {
    case Flavor.dev:
      options = const FirebaseOptions(
        apiKey: 'AIzaSyDevExampleKey',
        appId: '1:1234567890:android:dev123',
        messagingSenderId: '1234567890',
        projectId: 'my-app-dev',
      );
      break;
    case Flavor.staging:
      options = const FirebaseOptions(
        apiKey: 'AIzaSyStagingExampleKey',
        appId: '1:1234567890:android:staging123',
        messagingSenderId: '1234567890',
        projectId: 'my-app-staging',
      );
      break;
    case Flavor.production:
      options = const FirebaseOptions(
        apiKey: 'AIzaSyProdExampleKey',
        appId: '1:1234567890:android:prod123',
        messagingSenderId: '1234567890',
        projectId: 'my-app-prod',
      );
      break;
  }
  await Firebase.initializeApp(options: options);
}

// Enable Impeller debug flags in debug builds
void main() {
  if (kDebugMode) {
    // Log all Impeller shader compilations
    ImpellerDebug.setShaderCompilationLoggingEnabled(true);
    // Draw bounding boxes around all rendered layers
    ImpellerDebug.setLayerBoundsEnabled(true);
    // Log GPU command buffer submissions
    ImpellerDebug.setCommandBufferLoggingEnabled(true);
  }
  runApp(const MyApp());
}

// Sealed class for type-safe analytics events
sealed class AnalyticsEvent {
  final String name;
  final Map parameters;

  AnalyticsEvent(this.name, this.parameters);
}

class UserLoginEvent extends AnalyticsEvent {
  UserLoginEvent({
    required String userId,
    required String loginMethod,
  }) : super('user_login', {
          'user_id': userId,
          'login_method': loginMethod,
          'timestamp': DateTime.now().millisecondsSinceEpoch,
        });
}

class PurchaseEvent extends AnalyticsEvent {
  PurchaseEvent({
    required String userId,
    required double amount,
    required String currency,
  }) : super('purchase', {
          'user_id': userId,
          'amount': amount,
          'currency': currency,
          'timestamp': DateTime.now().millisecondsSinceEpoch,
        });
}

// Log event with compile-time type safety
void logAnalyticsEvent(AnalyticsEvent event) {
  FirebaseAnalytics.instance.logEvent(
    name: event.name,
    parameters: event.parameters,
  );
}