Riverpod state-management patterns, provider responsibilities, and local persistence.
Ponder uses Riverpod throughout the Flutter app. The project uses:
Provider for stateless dependencies such as Appwrite SDK clients, repositories, and services.StateProvider for simple mutable UI state such as current search query and selected search scope.FutureProvider for async read models such as profile, friends, received shares, starter fact-check claims, and search results.StreamProvider for the chat polling stream.StateNotifierProvider for auth, onboarding, fact-check submit state, and theme mode.AsyncNotifierProvider for feed sessions, saved item IDs, local feed preferences, feed tuning, and saved-note writes.| Provider | Type | Responsibility |
| — | — | — |
| authProvider | StateNotifierProvider | Current Appwrite user, user tier, loading/error state, sign-in/sign-up/sign-out. |
| currentUserProvider | Provider | Convenience projection of authProvider.currentUser. |
| routerProvider | Provider<GoRouter> | Route graph and shell setup. |
| themeModeProvider | StateNotifierProvider | Session-scoped ThemeMode. |
| appwriteClientProvider and SDK providers | Provider | Shared Appwrite client, Account, Databases, Functions, Storage. |
| tablesServiceProvider | Provider | TablesDB row operations. |
| Feature | Main providers |
| — | — |
| Article | factChecksProvider, saveStateProvider |
| Fact check | factCheckProvider, factCheckDraftClaimProvider, factCheckDraftSourceContentIdProvider, starterFactCheckClaimsProvider |
| Feed | forYouProvider, forYouRefreshSignalProvider, localFeedPreferencesProvider, feedPersonalizationSnapshotProvider, feedPreferencesMigrationProvider, feedTuningProvider |
| Friends | receivedSharesProvider, friendsListProvider, requestsProvider, friendThreadPreviewProvider, userSearchQueryProvider, userSearchResultsProvider, sharePreviewProvider |
| Thread | threadMessagesPollingIntervalProvider, threadParticipantProvider, threadArticleProvider, threadMessagesProvider |
| Profile | profileUserProvider, currentUserTierProvider, savedItemsProvider, savedItemIdsProvider, savedItemNoteProvider |
| Search | searchQueryProvider, searchScopeProvider, recentSearchesProvider, searchResultsProvider |
| Onboarding | onboardingProvider |
shared_preferences is used for lightweight local state:
onboarding.completed.v1: whether onboarding is complete.feed.preferences.onboarding.v1: onboarding interest picks.feed.preferences.more.v1: local preferred topics.feed.preferences.less.v1: local avoided topics.search.recent.v1: recent search terms.fc_date and fc_count: daily fact-check limit tracking.No other local storage mechanism is used in the current Flutter code.
Save mutations invalidate savedItemIdsProvider and savedItemsProvider. Profile edits invalidate profileUserProvider. Feed-tuning sync invalidates profile state after backend writes. Thread send invalidates the polling provider for that thread.
factChecksProvider and saveStateProvider use auto-dispose family providers with a two-minute keep-alive timer.
threadMessagesProvider is a StreamProvider.autoDispose.family built on a polling loop. It immediately fetches thread messages, then repeats after the configured polling interval of two seconds. This is a deliberate implementation in the code; no Appwrite realtime provider is active.