Firebase Setup

• Use firebase_core for initialization — call Firebase.initializeApp() before runApp()
• Use flutterfire configure for platform-specific setup
• Use separate Firebase projects per flavor (see app-config skill)
• Register Firebase services via injectable for consistent DI

Authentication

• Use firebase_auth for user management
• Wrap all auth calls in an AuthRepository — no direct FirebaseAuth usage in BLoCs or UI
• Support email/password, Google Sign-In, and Apple Sign-In at minimum
• Handle auth state changes via FirebaseAuth.instance.authStateChanges() stream in AuthBloc
• Store auth tokens via flutter_secure_storage — never in SharedPreferences or source code
• Implement proper sign-out: clear local cache, navigate to login, dispose user-specific BLoCs

Firestore

• Use cloud_firestore for remote data persistence
• DataSources wrap all Firestore calls (get, set, update, delete, snapshots)
• Use typed model classes with fromFirestore / toFirestore factory methods
• Prefer .withConverter<T>() for type-safe collection references
• Use batch writes for multi-document operations — never multiple sequential writes
• Implement offline persistence (enabled by default on mobile)

Security Rules

• NEVER rely on client-side validation alone — enforce rules in Firestore Security Rules
• Default deny: start with allow read, write: if false; and open only what's needed
• Always validate request.auth != null for authenticated-only collections
• Test rules with the Firebase Emulator Suite before deploying

Push Notifications (FCM)

• Use firebase_messaging for push notifications
• Request notification permissions early but gracefully (explain value before requesting)
• Handle foreground, background, and terminated-state messages separately
• Store FCM token in Firestore user document for server-side targeting
• Re-register token on onTokenRefresh stream

Crashlytics

• Use firebase_crashlytics for crash reporting
• Enable in staging and production flavors only — disable in dev
• Record Flutter errors: FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError
• Catch async errors via PlatformDispatcher.instance.onError
• Add custom keys for user context: Crashlytics.instance.setCustomKey('userId', id)

Analytics

• Use firebase_analytics for user behavior tracking
• Log meaningful events with descriptive names: analytics.logEvent(name: 'purchase_completed')
• Set user properties for segmentation: analytics.setUserProperty(name: 'plan', value: 'premium')
• Track screen views via FirebaseAnalyticsObserver in GoRouter
• NEVER log PII (emails, passwords, phone numbers) in analytics events

Remote Config

• Use firebase_remote_config for feature flags and A/B testing
• Set sensible defaults locally — app MUST work without Remote Config fetched
• Fetch and activate on app start with a timeout fallback
• Cache values and respect minimum fetch intervals to avoid throttling