# zellidev0/beercules_app_flutter architecture

> Architecture diagram of the GitHub repository zellidev0/beercules_app_flutter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zellidev0/beercules_app_flutter
- Repository: https://github.com/zellidev0/beercules_app_flutter

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Native Host Layer
    subgraph "Native Host" 
        direction TB
        AndroidApp["Android Embedding"]:::external
        iOSApp["iOS Embedding"]:::external
        WebHosting["Web Hosting (Firebase)"]:::external
    end

    %% Flutter Engine
    FlutterEngine["Flutter Engine"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer (UI)" 
        direction TB
        Screens["UI Screens"]:::ui
        Widgets["Shared Widgets"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic (Controllers & Providers)"
        direction TB
        HomeController["HomeController"]:::business
        HomeModel["HomeModel"]:::business
        HomeProviders["HomeProviders"]:::business

        GameController["GameController"]:::business
        GameModel["GameModel"]:::business
        GameProviders["GameProviders"]:::business

        CustomizeController["CustomizeController"]:::business
        CustomizeModel["CustomizeModel"]:::business
        CustomizeProviders["CustomizeProviders"]:::business
    end

    %% Services & Data Layer
    subgraph "Services & Data"
        direction TB
        subgraph "AdService"
            AdService["AdService"]:::service
            AdMobService["AdMobAdService"]:::service
            NoOpService["NoOpAdService"]:::service
        end
        subgraph "PersistenceService"
            Database["Database"]:::service
            SharedPrefs["SharedPrefsDatabase"]:::service
            Persistence["PersistenceService"]:::service
        end
        subgraph "NavigationService"
            NavigationAggregator["NavigationService Aggregator"]:::service
            GoRouterService["GoRouterNavigationService"]:::service
            Routes["Navigation Routes"]:::service
        end
        Codegen["Codegen Outputs"]:::codegen
        LocalDB["SQLite / SharedPreferences"]:::external
        AdMobSDK["Google Mobile Ads SDK"]:::external
    end

    %% CI/CD Layer
    subgraph "CI/CD & Deployment"
        direction TB
        GitLabCI[".gitlab-ci.yml"]:::ci
        AndroidBuild["build_release_android.sh"]:::ci
        DeployAndroid["deploy-android.sh"]:::ci
        DeployWeb["deploy-web.sh"]:::ci
        Fastlane["ios/fastlane"]:::ci
    end

    %% Connections
    AndroidApp --> FlutterEngine
    iOSApp --> FlutterEngine
    WebHosting --> FlutterEngine

    FlutterEngine --> Screens
    FlutterEngine --> Widgets

    Screens --> HomeController
    Screens --> GameController
    Screens --> CustomizeController

    HomeController --> HomeModel
    HomeController --> HomeProviders
    GameController --> GameModel
    GameController --> GameProviders
    CustomizeController --> CustomizeModel
    CustomizeController --> CustomizeProviders

    HomeController --> Persistence
    GameController --> Persistence
    CustomizeController --> Persistence

    Persistence --> LocalDB
    Persistence --> SharedPrefs

    HomeController --> AdService
    GameController --> AdService

    AdService --> AdMobSDK

    HomeController --> NavigationAggregator
    NavigationAggregator --> GoRouterService
    NavigationAggregator --> Routes

    Codegen --> Screens
    Codegen --> Widgets
    Codegen --> Routes

    %% CI/CD connections
    GitLabCI --> AndroidBuild
    GitLabCI --> DeployAndroid
    GitLabCI --> DeployWeb
    GitLabCI --> Fastlane

    %% Click Events
    click Screens "https://github.com/zellidev0/beercules_app_flutter/tree/main/lib/ui/screens"
    click Widgets "https://github.com/zellidev0/beercules_app_flutter/tree/main/lib/ui/widgets"
    click HomeController "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/home/home_controller.dart"
    click HomeModel "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/home/home_model.dart"
    click HomeProviders "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/home/home_providers.dart"
    click GameController "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/game/game_controller.dart"
    click GameModel "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/game/game_model.dart"
    click GameProviders "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/game/game_providers.dart"
    click CustomizeController "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/customize/customize_controller.dart"
    click CustomizeModel "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/customize/customize_model.dart"
    click CustomizeProviders "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/ui/screens/customize/customize_providers.dart"
    click AdService "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/ad_service/ad_service.dart"
    click AdMobService "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/ad_service/implementation/ad_mob_ad_service.dart"
    click NoOpService "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/ad_service/implementation/no_op_ad_service.dart"
    click Database "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/persistence/implementation/database/database.dart"
    click SharedPrefs "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/persistence/implementation/database/shared_prefs_database.dart"
    click Persistence "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/persistence/implementation/persistence_service.dart"
    click NavigationAggregator "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/navigation_service/navigation_service_aggregator.dart"
    click GoRouterService "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/navigation_service/implementation/go_router_navigation_service.dart"
    click Routes "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/services/navigation_service/navigation_service_routes.dart"
    click Codegen "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/gen/assets.gen.dart"
    click Codegen "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/gen/locale_keys.g.dart"
    click Codegen "https://github.com/zellidev0/beercules_app_flutter/blob/main/lib/go_router.g.dart"
    click AndroidApp "https://github.com/zellidev0/beercules_app_flutter/blob/main/android/app/src/main/java/io/flutter/app/FlutterMultiDexApplication.java"
    click iOSApp "https://github.com/zellidev0/beercules_app_flutter/blob/main/ios/Runner/AppDelegate.swift"
    click WebHosting "https://github.com/zellidev0/beercules_app_flutter/blob/main/web/index.html"
    click GitLabCI "https://github.com/zellidev0/beercules_app_flutter/blob/main/.gitlab-ci.yml"
    click AndroidBuild "https://github.com/zellidev0/beercules_app_flutter/blob/main/build_release_android.sh"
    click DeployAndroid "https://github.com/zellidev0/beercules_app_flutter/blob/main/deploy-android.sh"
    click DeployWeb "https://github.com/zellidev0/beercules_app_flutter/blob/main/deploy-web.sh"
    click Fastlane "https://github.com/zellidev0/beercules_app_flutter/tree/main/ios/fastlane"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef business fill:#d4edda,stroke:#155724,color:#155724
    classDef service fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef codegen fill:#f5c6cb,stroke:#721c24,color:#721c24
    classDef ci fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
