Core Concepts

One shared source, two profiles

The CLI generates the same Flutter source for both profiles and writes the choice to lib/config/bowlerkit_profile.dart:

• Account (account): online auth, remote preferences, Account notifications, and entitlement sync.
• Guest (guest): local-first runtime with no account API calls or remote auth state.

lib/config/app_mode.dart exposes appProfile, isAccountOnline, and isGuestLocal. Use these constants when adding profile-specific behavior instead of forking the mobile source.

Startup and routing

main.dart initializes time zones, AdMob, the native splash, local storage, onboarding state, localization, Riverpod, and AutoRoute. Account-only bootstrap wiring runs after the first frame so FCM/network work cannot block the first screen.

Guest startup ignores and clears Account tokens, starts local notification support, configures anonymous monetization, and routes to the local onboarding/home flow. Account startup restores the token/user state, validates the session, syncs pending preferences, and configures RevenueCat with the backend UUID.

bootstrap/account_bootstrap.dart also resolves the allowlisted Account deep-link contract and handles logout navigation. Guest mode never follows Account deep links.

State and data layers

• Riverpod 3 providers/notifiers — auth, user, preferences, notifications, security, theme, monetization.
• Dio — versioned API calls, bearer injection, error mapping, and response transforms.
• Dio cache interceptor + Drift store — optional read caching and stale-on-error behavior.
• SharedPreferences — local preferences and onboarding state.
• flutter_secure_storage — auth/FCM/user secrets.
• AutoRoute — generated route graph (app_router.dart/app_router.gr.dart).
• Freezed/JSON serialization — generated immutable models and parsers.

API boundary

DioService builds URLs as:

Endpoints.baseURL + /api/v1 + routePath

Set the host root via API_BASE_URL — the apiBaseUrl default in lib/config/app_env.dart or a --dart-define (see docs/ENVIRONMENT.md). Account requests use a Laravel Sanctum bearer token. Guest requests fail closed with Network requests are disabled for the Guest Local profile.

Laravel owns token issuance, migrations, uploads, webhooks, and destructive account operations. Go validates the same Sanctum tokens and serves protected /api/v1/app/* resources.

Add a feature safely

1. Decide whether the feature is shared, Account-only, or Guest-only.
2. Add models with Freezed/JSON annotations when a new response shape is needed.
3. Add a typed service/provider and keep network calls behind the Dio service.
4. Guard Account work with isGuestLocal and provider enabled/early-return logic.
5. Add/modify an AutoRoute page and regenerate code.
6. Persist local state through the existing storage/provider patterns; add a backend contract only for Account data.