# gskinnerteam/flutter-wonderous-app architecture

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

- Interactive diagram: https://gitdiagram.com/gskinnerteam/flutter-wonderous-app
- Repository: https://github.com/gskinnerteam/flutter-wonderous-app

## Overview

##### Project type and overall purpose
- Wonderous is a cross-platform Flutter application (mobile, desktop, web) that displays information, illustrations and media about famous world structures (“wonders”).
- It is purely client-side: a single codebase (Dart + Flutter) runs on multiple platforms via platform-specific embedders (Android, iOS, macOS, Windows, Web/WASM).
- It pulls some data from external services (e.g., Unsplash API) and bundles a large set of local data assets (JSON, images, fonts).

##### Top-level architecture and file structure patterns
- Platforms / Embedders:
– android/, ios/, macos/, windows/, web/ – platform-specific wrappers, Gradle/Xcode/CMake configs, native main files, Flutter engine integration.
- Application code:
– lib/ – the entire shared app code:
· lib/ui/ – presentation layer: screens, widgets, illustrations, theming
· lib/logic/ – business logic layer: state management, services, API logic, utilities, local persistence
· lib/logic/data/ – domain models and bundled JSON data
· lib/_tools/, py/, tools/ – build-time and development scripts for asset generation or data fetching
– assets/ – fonts, images, splash, marketing materials
- Configuration: pubspec.yaml, flutter_native_splash.yaml, l10n.yaml for localization.

##### How to represent this
- Flutter Engine & Shell (Dart VM or WASM runtime + rendering via Impeller or Skia)
- Shared Application Layer:
– UI Layer (widgets, screens, routing)
– Business Logic Layer (app_logic.dart, logic/*)
– Data Layer (domain models, artifact_data.dart, wonders_data/*.dart)
- Asset Bundle (images, fonts, l10n)
- External Services:
– Unsplash API
– Artifact API Service (if remote)
- Local Persistence (json_prefs_file mixin simulating settings/data storage)
- Platform Channels / Native Integrations (e.g., Native Widget Service for Home Screen widget on iOS/macOS)

1. Platform Embedders ↓ embed Flutter Engine
2. Flutter Engine ↔ Shared Application Layer
3. UI Layer → Business Logic Layer (user events, navigation)
4. Business Logic Layer → Data Layer (loading models)
5. Business Logic Layer ↔ External Services (HTTP REST calls via http_client.dart)
6. Business Logic Layer ↔ Local Persistence (settings, caching)
7. Business Logic Layer ↔ Platform Channels (for native widget updates)
8. UI Layer ← Asset Bundle (images, fonts, localized strings)

c. Architectural patterns and principles
- Layered architecture (Presentation → Domain/Logic → Data/Services)
- Single codebase, “write once, run everywhere” via Flutter’s platform embedder abstraction
- Separation of concerns: UI widgets don’t call REST directly; they go through logic/services
- Dependency inversion for HTTP and persistence (http_client.dart, json_prefs_file.dart)
- Asset-driven UI (all illustrations and data are bundled under logic/data and assets/)

d. Key technologies/frameworks
- Flutter + Dart
- Impeller Rendering on iOS (config in Runner configs)
- WASM target on Web
- Gradle/Kotlin DSL for Android embedder
- Xcode/Swift for iOS/macOS embedder
- CMake/C++ for Windows embedder
- HTTP via custom http_client.dart and retry/prefabrication helpers
- Local JSON persistence for settings/data

##### Elements
- Clear labels on every component (e.g., “Flutter Engine (Impeller/Skia)”, “lib/logic“, “Unsplash API”)
– Rectangles for code modules (UI, Logic, Data)

##### Final reminder
- Be detailed: capture each major module (UI, logic, data, assets, embedder layer, services).
- How the application is packaged once: a single asset bundle + Flutter engine delivered by each platform folder.
- Don’t overthink—split the codebase into logical components and show how they interact rather than every single file.

## Diagram (Mermaid)

```mermaid
graph TB

  subgraph "Platform Embedders" 
    Android["Android"]:::platform
    iOS["iOS"]:::platform
    macOS["macOS"]:::platform
    Windows["Windows"]:::platform
    Web["Web/WASM"]:::platform
  end

  FlutterEngine["Flutter Engine\n(Impeller/Skia)"]:::runtime

  subgraph "Shared Application Layer"
    Entry["lib/main.dart"]:::app
    Router["lib/router.dart"]:::app

    subgraph "UI Layer"
      UI["Presentation Widgets & Screens"]:::ui
    end

    subgraph "Business Logic Layer"
      Logic["Core Logic & Services"]:::logic
      HttpClient["http_client.dart"]:::logic
      JsonPrefs["json_prefs_file.dart"]:::logic
      UnsplashService["unsplash_service.dart"]:::logic
      ArtifactApiService["artifact_api_service.dart"]:::logic
      NativeWidgetService["native_widget_service.dart"]:::logic
    end

    subgraph "Data Layer"
      Data["Domain Models & Bundled JSON Data"]:::data
    end
  end

  AssetBundle["Asset Bundle\n(fonts, images, l10n)"]:::asset

  subgraph "External Services"
    UnsplashAPI["Unsplash API"]:::external
    ArtifactAPI["Artifact API Service"]:::external
  end

  Persistence["Local Persistence\n(JSON Prefs)"]:::persistence
  Channels["Platform Channels\n(Native Integrations)"]:::persistence

  subgraph "Build & Dev Tools"
    Tools["Asset/Data Generation Scripts"]:::tools
  end

  subgraph "Configuration"
    Config["pubspec.yaml\nflutter_native_splash.yaml\nl10n.yaml"]:::config
  end

  %% Connections
  Android --> FlutterEngine
  iOS --> FlutterEngine
  macOS --> FlutterEngine
  Windows --> FlutterEngine
  Web --> FlutterEngine

  FlutterEngine --> Entry
  Entry --> UI
  UI --> Logic
  Logic --> Data

  Logic --> UnsplashAPI
  Logic --> ArtifactAPI

  Logic --> Persistence
  Logic --> Channels

  UI --> AssetBundle

  Config --> Entry
  Tools --> Data

  %% Click Events
  click Android "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/android/"
  click iOS "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/ios/"
  click macOS "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/macos/"
  click Windows "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/windows/"
  click Web "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/web/"
  click Entry "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/lib/main.dart"
  click Router "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/lib/router.dart"
  click UI "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/lib/ui/"
  click Logic "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/lib/logic/"
  click Data "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/lib/logic/data/"
  click UnsplashService "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/lib/logic/unsplash_service.dart"
  click ArtifactApiService "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/lib/logic/artifact_api_service.dart"
  click HttpClient "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/lib/logic/common/http_client.dart"
  click JsonPrefs "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/lib/logic/common/json_prefs_file.dart"
  click NativeWidgetService "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/lib/logic/native_widget_service.dart"
  click Tools "https://github.com/gskinnerteam/flutter-wonderous-app/tree/main/lib/_tools/"
  click Config "https://github.com/gskinnerteam/flutter-wonderous-app/blob/main/pubspec.yaml"

  %% Styles
  classDef platform fill:#D0E8F2,stroke:#333,stroke-width:1px
  classDef runtime fill:#FADBD8,stroke:#333,stroke-width:1px
  classDef app fill:#D5F5E3,stroke:#333,stroke-width:1px
  classDef ui fill:#FCF3CF,stroke:#333,stroke-width:1px
  classDef logic fill:#FDEBD0,stroke:#333,stroke-width:1px
  classDef data fill:#D6EAF8,stroke:#333,stroke-width:1px
  classDef asset fill:#FCF0DA,stroke:#333,stroke-width:1px
  classDef external fill:#EAECEE,stroke:#333,stroke-width:1px
  classDef persistence fill:#D5DBDB,stroke:#333,stroke-width:1px
  classDef tools fill:#F9E79F,stroke:#333,stroke-width:1px
  classDef config fill:#A9DFBF,stroke:#333,stroke-width:1px
```
