How gskinnerteam/flutter-wonderous-app works
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.