Architecture Overview

​

Design Principles

​

Separation of Concerns

• Logic Layer (lib/logic/): Contains all business logic, state management, data models, and services
• UI Layer (lib/ui/): Contains widgets, screens, and visual components

• Business logic is reusable and testable
• UI components remain focused on presentation
• State management is centralized and predictable

​

Single Responsibility

• AppLogic: Application lifecycle and bootstrapping
• WondersLogic: Wonder data management
• SettingsLogic: User preferences and configuration
• CollectiblesLogic: Collectible items and discovery
• TimelineLogic: Historical timeline data
• ArtifactAPILogic: Artifact search and retrieval

​

Reactive State Management

• State changes propagate automatically to UI components
• UI widgets rebuild when watched values change
• Logic classes expose ValueNotifier properties for reactive updates

​

Key Technologies

​

Core Stack

​

Key Dependencies

• get_it: Service locator for dependency injection
• get_it_mixin: Reactive widget bindings to GetIt services
• provider: State management infrastructure
• go_router: Type-safe routing with deep linking support
• flutter_animate: Declarative animations

​

Application Layers

​

Presentation Layer

WondersApp (MaterialApp.router)
  └─ WondersAppScaffold (Theme & Style Provider)
      └─ Screen Widgets
          └─ Common Controls & Components

• WondersAppScaffold: Root scaffold providing app-wide theme and styling
• Screen widgets: Feature-specific screens (home, wonder details, timeline, etc.)
• Common controls: Reusable UI components (buttons, images, modals)

​

Business Logic Layer

// Registration in main.dart
void registerSingletons() {
  GetIt.I.registerLazySingleton<AppLogic>(() => AppLogic());
  GetIt.I.registerLazySingleton<WondersLogic>(() => WondersLogic());
  GetIt.I.registerLazySingleton<SettingsLogic>(() => SettingsLogic());
  // ... more services
}

// Access via global getters
AppLogic get appLogic => GetIt.I.get<AppLogic>();

​

Data Layer

• Wonder Data (lib/logic/data/wonders_data/): Static wonder information
• Collectible Data: Collectible items for each wonder
• Timeline Data: Historical events and timeline information
• Artifact Data: Museum artifact metadata

​

Service Layer

• ArtifactAPIService: Metropolitan Museum of Art API integration
• UnsplashLogic: Photo discovery and display
• NativeWidgetService: Home screen widget integration
• LocaleLogic: Internationalization and localization

​

Application Bootstrap

1. Initialization: Initialize Flutter bindings and platform services
2. Singleton Registration: Register all logic controllers and services
3. App Launch: Create and run WondersApp widget
4. Bootstrap: Load settings, locale, data, and collectibles
5. Navigation: Route to intro or home screen based on onboarding status

void main() async {
  WidgetsBinding widgetsBinding = WidgetsFlutterBinding.ensureInitialized();
  
  // Preserve splash screen during bootstrap
  if (!kIsWeb) {
    FlutterNativeSplash.preserve(widgetsBinding: widgetsBinding);
  }
  
  // Register singletons
  registerSingletons();
  
  // Run app
  runApp(WondersApp());
  
  // Bootstrap logic
  await appLogic.bootstrap();
  
  // Remove splash screen
  FlutterNativeSplash.remove();
}

​

Platform Support

• Mobile: iOS and Android with native integrations
• Desktop: Windows and macOS with adaptive layouts
• Web: WASM-optimized web builds at wonderous.app/web

​

Platform-Specific Optimizations

• iOS: Uses Impeller rendering engine by default
• Android: High refresh rate display support
• Desktop: Minimum window size constraints
• Web: Automatic accessibility features and image precaching

​

Performance Considerations

​

Image Caching

• Custom ImageCache with 250MB maximum size
• Strategic image precaching on web platform
• Lazy loading for wonder images and icons

​

Responsive Design

• Dynamic layout switching (portrait/landscape)
• Device size-based UI decisions (navigation rail vs. bottom nav)
• Adaptive orientation locking on smaller devices

​

Animation Control

• Honors system “reduce motion” settings
• Configurable animation timing through $styles.times
• Fade transitions for smooth screen changes

​

Next Steps