# stef-gms/flutter-games-endless_runner architecture

> Architecture diagram of the GitHub repository stef-gms/flutter-games-endless_runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stef-gms/flutter-games-endless_runner
- Repository: https://github.com/stef-gms/flutter-games-endless_runner

## Overview

##### Main Components
- Frontend/Game UI: Highlight the Flutter UI using several screens including Main Menu (found in lib/main_menu), game screen/FlameGame’s components (lib/flame_game), level selection screens (lib/level_selection), and settings screens (lib/settings).
- Game Engine Components: Emphasize the use of Flame’s game engine. Include the FlameGame base along with associated game objects (player, obstacle, background, effects) as separate subcomponents.
- Audio Subsystem: Represent the audio files and controllers (lib/audio) that manage soundtracks and effects (assets/music, assets/sfx).
- Persistence and Settings: Identify the persistence layers for settings and player progress (lib/settings/persistence and lib/player_progress/persistence) that encapsulate low-level storage (using local storage or memory-based approaches).
- Routing and Lifecycle: Include components for navigation and overall app lifecycle management (router in lib/router and app lifecycle in lib/app_lifecycle).

##### Relationships and Interactions
- How the game components talk to the audio subsystem for triggering sound effects, as well as how they interface with the settings and persistence modules.
- Platform-specific layer as the “shell” that loads the Flutter engine and binds native functionality, while the bulk of the application logic exists in lib.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly delineate UI, game logic, audio, and persistence functionalities.
- Integration Readiness: Detect integration points for external services (logging via the logging package, potential ads or analytics for production) so that they can be noted as optional add-ons.

##### Relevant Technologies, Frameworks, and Dependencies
- Flutter for UI and multi-platform support.
- Flame for the game engine and managing game objects.
- Shared Preferences for settings storage.
- The logging package for debug and production logging.
- Third-party tools (like flutter_launcher_icons) used for assets management.
- For multi-platform builds, note the directories for iOS, Android, Web, Linux, macOS, and Windows.

- Separate the core game engine (FlameGame and related lib components) from the frontend screens (menus, level selection, settings).
- For each major module, include sub-components where applicable (e.g., under the FlameGame module, show player, obstacle, and background components).
- Integration of persistent data storage for player progress and settings.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend/Game UI Layer
    subgraph "Frontend/Game UI"
        A["Main Menu UI"]:::ui
        B["Game Screen & FlameGame Base"]:::ui
        C["Level Selection Screen"]:::ui
        D["Settings Screen"]:::ui
    end

    %% Game Engine Components Layer
    subgraph "Game Engine Components"
        E["FlameGame (Core Engine)"]:::game
        F["Game Objects"]:::game
        G["Effects"]:::game
    end

    %% Audio Subsystem
    subgraph "Audio Subsystem"
        H["Audio Controller"]:::audio
    end

    %% Persistence and Settings
    subgraph "Persistence and Settings"
        I["Settings Persistence"]:::persistence
        J["Player Progress Persistence"]:::persistence
    end

    %% Routing and Lifecycle
    subgraph "Routing and Lifecycle"
        K["Router"]:::routing
        L["App Lifecycle"]:::routing
    end

    %% Platform Integration Layer
    subgraph "Platform Shell"
        M["Android"]:::platform
        N["iOS"]:::platform
        O["Web"]:::platform
        P["Linux"]:::platform
        Q["macOS"]:::platform
        R["Windows"]:::platform
    end

    %% Relationships
    %% Navigation Flow from UI to Game Engine
    A -->|"navigatesTo"| B
    C -->|"selects"| B
    D -->|"configures"| I

    %% Game Screen integrates with Game Engine
    B -->|"launches"| E

    %% FlameGame core uses its subcomponents
    E -->|"uses"| F
    E -->|"triggers"| G

    %% Game Engine interacts with Persistence and Audio
    E -->|"updatesProgress"| J
    E -->|"callsAudio"| H

    %% Game Engine communicates with Lifecycle and Router
    E -->|"managesLife"| L
    E -->|"routesThrough"| K

    %% Platform Shell loads and binds the application
    M ---|"loads"| A
    N ---|"loads"| A
    O ---|"loads"| A
    P ---|"loads"| A
    Q ---|"loads"| A
    R ---|"loads"| A

    %% Styling
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef game fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef audio fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef persistence fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef routing fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef platform fill:#e2e3e5,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/stef-gms/flutter-games-endless_runner/blob/master/lib/main_menu/main_menu_screen.dart"
    click B "https://github.com/stef-gms/flutter-games-endless_runner/blob/master/lib/flame_game/endless_runner.dart"
    click B "https://github.com/stef-gms/flutter-games-endless_runner/blob/master/lib/flame_game/game_screen.dart"
    click C "https://github.com/stef-gms/flutter-games-endless_runner/blob/master/lib/level_selection/level_selection_screen.dart"
    click D "https://github.com/stef-gms/flutter-games-endless_runner/blob/master/lib/settings/settings_screen.dart"
    click F "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/lib/flame_game/components"
    click G "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/lib/flame_game/effects"
    click H "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/lib/audio"
    click I "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/lib/settings/persistence"
    click J "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/lib/player_progress/persistence"
    click K "https://github.com/stef-gms/flutter-games-endless_runner/blob/master/lib/router.dart"
    click L "https://github.com/stef-gms/flutter-games-endless_runner/blob/master/lib/app_lifecycle/app_lifecycle.dart"
    click M "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/android"
    click N "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/ios"
    click O "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/web"
    click P "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/linux"
    click Q "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/macos"
    click R "https://github.com/stef-gms/flutter-games-endless_runner/tree/master/windows"
```
