How zellidev0/beercules_app_flutter works
Project type and purpose
• Beercules is a cross-platform Flutter application (Android, iOS, Web) implementing a drinking game.
• It contains no remote backend or microservices—state is stored locally (SQLite and/or SharedPreferences) and ads are served via AdMob.
File structure
• Top-level:
• android/ & ios/ folders: native embedding projects, build scripts (Gradle, Xcode, Fastlane).
• web/: Flutter’s web build and Firebase hosting config.
• lib/: Dart source code organized into:
– main.dart & go_router.dart (app entrypoint and navigation)
– common/ (theme, constants, utilities)
– services/ (ad_service, navigation_service, persistence)
– ui/ (screens by feature, shared widgets)
– gen/ (codegen outputs: assets, localization keys)
• Tests and CI/CD:
• .gitlab-ci.yml, build_release_android.sh, deploy-*.sh
• Fastlane under ios/fastlane for iOS deployments
README for additional insights
• Confirms Flutter cross-platform nature, user-focused UI, open-source contributions process.
• No remote API dependencies beyond AdMob and optional Firebase hosting for web.
a. Main components
1. Presentation Layer (Flutter UI)
– Widgets, Screens (Landing, Home, Customize, Game, Rules)
2. State & Business Logic Layer
– Controllers, Models, Providers (Freezed + Riverpod/Provider patterns)
3. Services Layer
– AdService (AdMob integration)
– PersistenceService (SQLite via floor/moor or SharedPrefs)
– NavigationService (GoRouter abstraction)
4. Platform & External Dependencies
– Local DB / SharedPreferences
– AdMob / Google Mobile Ads SDK
– Firebase Hosting (web)
5. Native Embedding
– Android embedding (FlutterMultiDexApplication, Gradle)
– iOS embedding (AppDelegate.swift, CocoaPods, Fastlane)
6. CI/CD Pipeline
– GitLab CI, shell scripts, Fastlane
b. Relationships & data flow
1. User taps a UI control → Presentation Layer invokes Controller/Provider.
2. Controller calls into Services Layer (e.g., PersistenceService.saveGameState).
3. PersistenceService writes to local DB or SharedPreferences.
4. Controller updates UI via state streams/providers.
5. AdService fetches ads from AdMob and surfaces them in banner or interstitial widgets.
6. NavigationService uses GoRouter to manage screen transitions.
7. Web deployment served via Firebase Hosting uploading build/web.
c. Architectural patterns & design principles
• Layered architecture (UI, State, Services, Data)
• MVVM-style with ViewModels/Controllers + Providers
• Dependency injection via aggregators (service_aggregator files)
• Code generation: Freezed for immutable models, JsonSerializable, GoRouter codegen
d. Key technologies/frameworks
• Flutter & Dart
• GoRouter (navigation)
• Freezed + json_serializable (model codegen)
• SharedPreferences & SQLite (local persistence)
• Google Mobile Ads (AdMob)
• Fastlane (iOS deploy), Gradle (Android build)
• GitLab CI, shell scripts for automated builds
Detail without overthinking
• Break out each lib/services sub-component if necessary.
• Codegen artifacts (gen) feeding into both UI and services.