Ponder

Flutter Project Structure

Source layout, feature boundaries, and naming conventions under lib/.

Top-Level Files

| Path | Purpose | | — | — | | lib/main.dart | Flutter entrypoint; loads .env, initializes Sentry, conditionally starts New Relic Mobile, starts ProviderScope. | | lib/app.dart | Builds MaterialApp.router, watches auth, feed-preference migration, router, and theme state. | | lib/utils/format_utils.dart | Shared formatting utilities used by UI code. |

Core

| Directory | Purpose | | — | — | | lib/core/constants/ | Appwrite IDs and environment-backed configuration. | | lib/core/enums/ | Shared enum types such as UserTier. | | lib/core/monitoring/ | Monitoring adapters such as conditional New Relic Mobile startup, navigation observers, auth context, Appwrite operation metrics, and handled-error events. | | lib/core/providers/ | App-wide providers such as auth state. | | lib/core/router/ | go_router route definitions. | | lib/core/services/ | Appwrite clients, TablesDB wrapper, repositories, auth/profile/like services. | | lib/core/shell/ | Persistent shell UI with bottom navigation and onboarding trigger. | | lib/core/theme/ | Color tokens, Material theme, gradients, tag/chip components, theme-mode provider. |

Features

| Directory | Active files in this snapshot | | — | — | | lib/features/article/ | Models, providers, ArticleDetailScreen. | | lib/features/fact_check/ | Result model, provider, FactCheckScreen, FactResultCard. | | lib/features/for_you/ | Personalization model, providers, feed repository, ForYouScreen. | | lib/features/friends/ | Models, providers, service, thread cipher, FriendsScreen, ThreadScreen, share sheet. | | lib/features/onboarding/ | Onboarding provider and OnboardingScreen. | | lib/features/profile/ | Profile providers, profile/archive/edit/saved screens, save gate, auth sheets, saved grid. | | lib/features/search/ | Search models, provider, screen, repository. |

Some feature folders contain empty models, services, widgets, or screens subdirectories. Those are present in the repository tree but have no Dart files in this snapshot.

Shared

| Directory | Purpose | | — | — | | lib/shared/models/ | Cross-feature data models such as ContentItem, UserProfile, SavedContentEntry, FeedPreferences, and fact-check history entries. | | lib/shared/utils/ | Shared utilities such as profile-image URL helpers and random feed session management. | | lib/shared/widgets/ | Reusable UI widgets including content cards, loading/error states, avatars, gradient buttons, and note editor sheets. |

Naming Conventions

• Screens use *Screen names and live under features/<feature>/screens.
• Riverpod provider files live under features/<feature>/providers or core/providers.
• Backend/data access classes are named *Service or *Repository.
• Shared models use immutable value-style classes and parsing factories such as fromRow or fromMap.
• Appwrite table and function IDs are centralized in AppwriteConfig.

Architecture Convention

The active code follows feature-first organization while keeping backend access out of widgets. A screen reads or writes state through providers; providers call services or repositories; services call TablesService, Appwrite SDK clients, or Appwrite Functions.