Flutter App Structure

The BookWish Flutter app follows a feature-based organizational structure with clear separation of concerns.

Directory Layout

app/lib/
├── api/                    # API client and models
│   ├── api_client.dart    # HTTP client with auth
│   ├── api_exception.dart # Error handling
│   └── models/            # Data models
├── config/                # App configuration
│   ├── routes.dart        # GoRouter configuration
│   ├── theme.dart         # Theme and typography
│   └── constants.dart     # App constants
├── hooks/                 # Custom Flutter hooks
│   └── use_tier_gate.dart # Subscription gating
├── services/              # Business logic layer
│   ├── auth_service.dart
│   ├── wishlist_service.dart
│   └── ...                # Feature-specific services
├── state/                 # Riverpod providers
│   ├── auth_provider.dart
│   ├── wishlist_provider.dart
│   ├── cart_provider.dart
│   └── ...                # Feature-specific state
├── ui/                    # User interface
│   ├── app_shell.dart     # Bottom nav shell
│   ├── components/        # Reusable components
│   ├── dialogs/           # Modal dialogs
│   ├── overlays/          # Bottom sheet overlays
│   ├── pages/             # Full-screen pages
│   └── widgets/           # Shared widgets
├── utils/                 # Utilities
│   ├── storage.dart       # Secure storage
│   ├── logger.dart        # Logging utilities
│   └── browser_hints.dart # Feature hints
├── app.dart               # Root app widget
└── main.dart              # Entry point

Key Files

File	Purpose
/lib/main.dart	App entry point, Firebase initialization
/lib/app.dart	Root MaterialApp with Riverpod and routing
/lib/config/routes.dart	GoRouter configuration with auth guards
/lib/config/theme.dart	Theme, colors (inkBlue, parchment, amberStar), typography (Merriweather for book titles, sans-serif for UI)
/lib/ui/app_shell.dart	Bottom navigation shell for main tabs
/lib/state/auth_provider.dart	Authentication state management
/lib/api/api_client.dart	HTTP client with interceptors for auth tokens
/lib/utils/storage.dart	Secure token storage using Hive and SharedPreferences

Organizational Conventions

Models

• Located in /lib/api/models/
• Data classes with fromJson and toJson methods
• Immutable with copyWith methods
• Example: User, Book, Wishlist, Cart

Services

• Located in /lib/services/
• Handle API calls and business logic
• Accept ApiClient in constructor
• Pure Dart classes, no Flutter dependencies
• Pattern: class XService { final ApiClient _api; XService(this._api); }

Providers

• Located in /lib/state/
• Use Riverpod with @riverpod annotation
• Auto-generated with build_runner
• Manage application state
• Pattern: @riverpod class XNotifier extends _$XNotifier { ... }

Pages

• Located in /lib/ui/pages/
• Organized by feature (auth, wish, read, shop, cart, etc.)
• Full-screen views with routes
• Use ConsumerWidget or ConsumerStatefulWidget

Components

• Located in /lib/ui/components/
• Feature-specific reusable widgets
• Examples: BookCard, ClubCard, ChallengeCard, LikeButton

Widgets

• Located in /lib/ui/widgets/
• Shared UI elements across features
• Examples: BwScaffold, BrowserOverlay, MainTabAppBar, UpgradePrompt

Overlays

• Located in /lib/ui/overlays/
• Bottom sheet overlays using DraggableScrollableSheet
• Examples: BookInfoOverlay, SettingsOverlay, ProfileOverlay

Code Generation

The app uses build_runner for code generation:

# Generate code (Riverpod providers)
flutter pub run build_runner build --delete-conflicting-outputs

# Watch mode for development
flutter pub run build_runner watch --delete-conflicting-outputs

Generated files have .g.dart extension and are gitignored except for Firebase options.

Platform-Specific Code

iOS

• Configuration in /ios/
• Info.plist contains permissions and schemes
• Runner.entitlements for app capabilities
• Podfile for native dependencies

Android

• Configuration in /android/
• AndroidManifest.xml for permissions
• build.gradle.kts for dependencies
• Google services configuration

Web

• Limited support (landing page only)
• Uses conditional imports with kIsWeb
• Main app targets mobile platforms