Providers topic

Providers

State lives in Riverpod providers, generated from @riverpod annotations via riverpod_generator. There are roughly 145 providers split across 14 files in lib/presentation/providers/.

Annotation styles

  • @riverpod (function form) — for read-only async values, derived state, and cached fetches.
  • @Riverpod(keepAlive: true) (class form) — for stateful notifiers (mutable state, mutations with loading/error, imperative operations).

Both generate a *.g.dart file living next to the source; imports look like:

part 'my_provider.g.dart';

@riverpod
Future<List<Topic>> topicsForBook(Ref ref, String bookId) async {
  final datasource = ref.watch(supabaseDatasourceProvider);
  return datasource.fetchTopics(bookId);
}

File breakdown

File Scope
providers.dart Core singletons: supabaseDatasource, aiDatasource, localEmbedding, secure storage, HTTP client. Imported by nearly every other provider file.
auth_provider.dart Auth state, current user, sign-in/out. Watched by the router for auth guards.
org_providers.dart Current org, org members, roles, team membership, manager assignments. Eagerly initialized after sign-in.
onboarding_provider.dart 5-step first-connection flow state (display name → persona → invitations → tour → admin wizard).
entitlement_providers.dart Feature-flag lookups; role_gate.dart consumes these to show/hide UI.
notification_providers.dart FCM registration, device-token rotation, local notification scheduling.
billing_providers.dart, revenuecat_providers.dart Subscription state from Supabase + RevenueCat.
quota_providers.dart Per-user quota lookups (AI tokens, audio minutes).
mfa_provider.dart MFA enrollment + verification flow.
card_generation_provider.dart Review-card generation mutations (async, show-loading pattern).
user_prefs_provider.dart Last-used org, persona, display preferences.
grants_providers.dart OAuth grants (Google, Notion, Slack, Lucca).
functions_status_provider.dart Edge Function health checks on BYO Supabase.

Naming conventions

  • Lowercase snake_case function providers: selectedAiProvider, useAiProxy, localEmbedding.
  • CamelCase class providers: AuthNotifier, OnboardingController.
  • Suffix-less providers for singletons: supabaseDatasource (one instance for the app).
  • Suffix -Provider on generated symbols: supabaseDatasourceProvider is what you ref.watch — the generator produces this name.

Eager initialization

main.dart wraps MaterialApp.router in a Consumer that watches authStateProvider, currentOrgProvider, and notificationListenersProvider eagerly. This is the riverpod-eager-initialization pattern — some state must be ready before the router runs so auth guards and deep-link handlers see consistent values.

Properties

supabaseDatasourceProvider → Provider<SupabaseDatasource> Providers
Root SupabaseDatasource singleton. Every screen/provider that reads Supabase data watches this provider — it's the one-and-only instance wired to Supabase.instance.client. Kept alive for the app lifetime.
final

Functions

supabaseDatasource(Ref<Object?> ref) → SupabaseDatasource Providers
Root SupabaseDatasource singleton. Every screen/provider that reads Supabase data watches this provider — it's the one-and-only instance wired to Supabase.instance.client. Kept alive for the app lifetime.