appiq-solution 1.2.0 → 1.3.0

package/#NEW APP PROMPT/ARCHITECTURE.md

@@ -0,0 +1,279 @@
+# Flutter App Scalable Skeleton Architecture
+
+This document describes a scalable, production-ready Flutter app architecture skeleton. It is designed for direct use in modern IDEs (Cursor AI, VSCode, etc.) and sets up best practices for maintainability, modularity, and extensibility.
+
+---
+
+## 1. Project Structure
+
+```
+/lib
+  /core
+    /constants
+    /exceptions
+    /extensions
+    /localization
+    /network
+    /theme
+    /utils
+    /widgets
+    app.dart
+    providers.dart
+  /features
+    /auth
+      /data
+        auth_repository.dart
+        models/
+      /domain
+        entities/
+        usecases/
+      /presentation
+        /screens
+          login_screen.dart
+          signup_screen.dart
+        /widgets
+        /providers
+    /onboarding
+      /presentation
+        onboarding_screen.dart
+    /profile
+      /data
+      /domain
+      /presentation
+        profile_screen.dart
+        settings_screen.dart
+    /dashboard
+      /presentation
+        dashboard_screen.dart
+    /splash
+      /presentation
+        splash_screen.dart
+  /l10n
+    intl_en.arb
+    intl_de.arb
+    ...
+  main.dart
+/test
+  /features
+  /core
+  /widgets
+/assets
+  /images
+  /icons
+  /fonts
+  /translations
+/ios
+/android
+/.github
+  workflows/
+fastlane/
+.gitignore
+pubspec.yaml
+README.md
+analysis_options.yaml
+```
+
+---
+
+## 2. Key Packages
+
+- **State Management:** riverpod, flutter_riverpod, riverpod_annotation, riverpod_generator
+- **Routing:** go_router
+- **Localization:** flutter_localizations, intl, easy_localization
+- **Theming:** flex_color_scheme or built-in ThemeData
+- **Auth:** firebase_auth or supabase_auth (optional, interface-based)
+- **Networking:** dio or http
+- **Model Generation:** freezed, json_serializable, build_runner
+- **CI/CD:** GitHub Actions, Fastlane
+- **Testing:** flutter_test, mocktail, integration_test
+- **Linting:** very_good_analysis or custom analysis_options.yaml
+- **Other:** flutter_svg, cached_network_image, shared_preferences, equatable
+
+---
+
+## 3. Layered Architecture
+
+- **core:** Shared app-wide utilities, themes, localization, providers, base widgets.
+- **features:** Each feature is self-contained with its own data/domain/presentation layers.
+  - **data:** Repositories, models, datasources (API, local).
+  - **domain:** Entities, usecases, business logic.
+  - **presentation:** Screens, widgets, providers.
+- **l10n:** Localization files.
+- **assets:** Images, icons, fonts, translations.
+
+---
+
+## 4. Example Folder & File Structure
+
+### /lib/core
+- `constants/` – app-wide constants (strings, keys, etc)
+- `exceptions/` – custom exceptions
+- `extensions/` – Dart/Flutter extension methods
+- `localization/` – localization setup
+- `network/` – API clients, interceptors
+- `theme/` – light/dark themes, theme provider
+- `utils/` – helpers, formatters
+- `widgets/` – reusable widgets (e.g., AppButton, AppTextField)
+- `app.dart` – root MaterialApp/Router setup
+- `providers.dart` – global providers (e.g., theme, locale)
+
+### /lib/features/auth
+- `data/auth_repository.dart` – interface + impl for auth
+- `data/models/user_model.dart` – generated with freezed/json_serializable
+- `domain/entities/user.dart`
+- `domain/usecases/login.dart`, `logout.dart`
+- `presentation/screens/login_screen.dart`, `signup_screen.dart`
+- `presentation/widgets/auth_form.dart`
+- `presentation/providers/auth_provider.dart` – Riverpod
+
+### /lib/features/onboarding
+- `presentation/onboarding_screen.dart`
+
+### /lib/features/profile
+- `presentation/profile_screen.dart`, `settings_screen.dart`
+
+### /lib/features/dashboard
+- `presentation/dashboard_screen.dart`
+
+### /lib/features/splash
+- `presentation/splash_screen.dart`
+
+---
+
+## 5. Riverpod State Management (with Annotations)
+
+- Use `@riverpod` annotation for providers.
+- Organize providers by feature in `/presentation/providers/`.
+- Example:
+  ```dart
+  // lib/features/auth/presentation/providers/auth_provider.dart
+  import 'package:riverpod_annotation/riverpod_annotation.dart';
+  part 'auth_provider.g.dart';
+
+  @riverpod
+  class AuthNotifier extends _$AuthNotifier {
+    // ...
+  }
+  ```
+- Run code generation:
+  ```
+  flutter pub run build_runner build --delete-conflicting-outputs
+  ```
+
+---
+
+## 6. Model Generation
+
+- Use `freezed` for immutable models:
+  ```dart
+  @freezed
+  class User with _$User {
+    const factory User({
+      required String id,
+      required String email,
+      // ...
+    }) = _User;
+
+    factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+  }
+  ```
+- Use `json_serializable` for JSON (de)serialization.
+
+---
+
+## 7. Theming (Dark/Light Mode)
+
+- Define themes in `/core/theme/`.
+- Provide theme switching via Riverpod provider.
+- Use `ThemeMode.system` as default.
+
+---
+
+## 8. Localization (i18n)
+
+- Place `.arb` files in `/l10n/`.
+- Use `flutter_localizations` and `intl`.
+- Provide a locale provider for switching languages.
+
+---
+
+## 9. Auth, Onboarding, Profile, Settings, Splash, Dashboard
+
+- Each screen in its own feature folder.
+- Use GoRouter for navigation.
+- Auth flow: Splash → Onboarding (if first launch) → Auth (login/signup) → Dashboard → Profile/Settings.
+
+---
+
+## 10. CI/CD & Fastlane
+
+- **GitHub Actions:** for static analysis, tests, build, deploy.
+- **Fastlane:** for iOS/Android build & release automation.
+- Example workflow: `.github/workflows/flutter.yml`
+- Fastlane setup in `/fastlane/` (see [Fastlane docs](https://docs.fastlane.tools/getting-started/ios/setup/)).
+
+---
+
+## 11. Example pubspec.yaml (excerpt)
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+  riverpod: ^3.0.0
+  flutter_riverpod: ^3.0.0
+  riverpod_annotation: ^3.0.0
+  go_router: ^13.0.0
+  freezed_annotation: ^2.4.1
+  json_serializable: ^6.7.1
+  intl: ^0.18.1
+  flex_color_scheme: ^7.3.1
+  dio: ^5.4.0
+  shared_preferences: ^2.2.2
+  flutter_svg: ^2.0.9
+  cached_network_image: ^3.3.1
+  equatable: ^2.0.5
+dev_dependencies:
+  riverpod_generator: ^3.0.0
+  build_runner: ^2.4.7
+  freezed: ^2.4.6
+  flutter_test:
+    sdk: flutter
+  very_good_analysis: ^5.1.0
+```
+
+---
+
+## 12. Additional Settings
+
+- `analysis_options.yaml` for linting.
+- `.env` for environment variables (use `flutter_dotenv` if needed).
+- README with setup, build, and contribution instructions.
+
+---
+
+## 13. Example Widget Structure
+
+- `AppScaffold` (core widget for consistent layout)
+- `AppButton`, `AppTextField` (core reusable widgets)
+- Feature-specific widgets in `/features/{feature}/presentation/widgets/`
+
+---
+
+## 14. Onboarding & Auth Flow
+
+- SplashScreen → OnboardingScreen (if first launch) → LoginScreen/SignupScreen → DashboardScreen → Profile/Settings
+
+---
+
+## 15. How to Use
+
+- Copy this structure as your base.
+- Scaffold folders/files as per above.
+- Add features by duplicating the feature folder pattern.
+- Use Riverpod for all state management.
+- Generate models and providers with build_runner.
+- Add translations in `/l10n/`.
+- Set up CI/CD and Fastlane as per documentation.

package/#NEW APP PROMPT/ARCHITECTURE_UNIFIED.md

@@ -0,0 +1,414 @@
+# Unified Flutter Project Architecture Documentation
+
+## Overview
+
+This document combines the best practices and details from both a scalable Flutter skeleton and the AiGo project architecture. It is designed to be directly usable in modern IDEs (Cursor AI, VSCode, etc.) and provides a solid, extensible, and production-ready foundation for any modern Flutter app.
+
+---
+
+## 1. High-Level Principles
+
+- **Clean Architecture**: Clear separation of UI, domain logic, and data sources.
+- **Feature Modularity**: Each feature is self-contained, following a data/domain/presentation split.
+- **State Management**: Riverpod (with annotations/codegen) for robust, testable state.
+- **Dependency Injection**: Riverpod for providers, GetIt for global services.
+- **Code Generation**: Use of freezed, json_serializable, and build_runner to reduce boilerplate.
+- **Internationalization**: Multi-language support with ARB files and codegen.
+- **Theming**: Light/dark mode with easy switching.
+- **Testing & CI/CD**: Comprehensive test setup, GitHub Actions, and Fastlane for automation.
+- **Responsiveness**: Adaptive UI for mobile, tablet, and web.
+- **Cloud Integration**: (Optional) Firebase Auth, Firestore, Storage.
+
+---
+
+## 2. Folder Structure
+
+```
+lib/
+├── core/                # Core utilities and shared components
+│   ├── config/          # App configuration
+│   ├── initialization/  # App initialization logic
+│   ├── json_converters/ # JSON conversion helpers
+│   ├── locale/          # Locale handling
+│   ├── location/        # Location services
+│   ├── mixins/          # Reusable mixins
+│   ├── network/         # Network utilities
+│   ├── routing/         # Routing configuration
+│   ├── services/        # Core services
+│   ├── storage/         # Local storage
+│   ├── theme/           # Theme configuration
+│   ├── utils/           # Utility functions
+│   └── widgets/         # Shared widgets
+│
+├── data/                # Data layer
+│   ├── datasources/     # Data sources (local, remote)
+│   ├── dtos/            # Data Transfer Objects
+│   ├── mappers/         # DTO <-> domain model mappers
+│   └── repositories/    # Repository implementations
+│
+├── domain/              # Domain layer
+│   ├── models/          # Domain models
+│   ├── repositories/    # Repository interfaces
+│   └── usecases/        # Business logic use cases
+│
+├── l10n/                # Localization
+│   ├── app_*.arb        # Translation files for different languages
+│   └── generate_translations.py # Script to manage translations
+│
+├── views/               # UI components organized by feature
+│   ├── event/           # Event feature module
+│   ├── home/            # Home feature
+│   ├── place/           # Place feature
+│   ├── plan/            # Plan feature
+│   ├── profile/         # Profile feature
+│   ├── settings/        # Settings feature
+│   └── onboarding/      # Onboarding feature
+│
+├── service_locator.dart # Dependency injection (GetIt)
+├── app.dart             # App configuration
+└── main.dart            # Entry point
+
+test/
+  /features
+  /core
+  /widgets
+assets/
+  /images
+  /icons
+  /fonts
+  /translations
+.ios/
+.android/
+.github/
+  workflows/
+fastlane/
+.gitignore
+pubspec.yaml
+README.md
+analysis_options.yaml
+```
+
+---
+
+## 3. Key Packages
+
+- **State Management:** riverpod, flutter_riverpod, riverpod_annotation, riverpod_generator
+- **Dependency Injection:** get_it
+- **Routing:** go_router
+- **Localization:** flutter_localizations, intl, easy_localization
+- **Theming:** flex_color_scheme or ThemeData
+- **Networking:** dio or http
+- **Model Generation:** freezed, json_serializable, build_runner
+- **CI/CD:** GitHub Actions, Fastlane
+- **Testing:** flutter_test, mocktail, integration_test
+- **Linting:** very_good_analysis or custom analysis_options.yaml
+- **Other:** flutter_svg, cached_network_image, shared_preferences, equatable
+- **Cloud (optional):** firebase_auth, cloud_firestore, firebase_storage
+
+---
+
+## 4. Core Architecture
+
+### Dependency Injection
+
+- Use **GetIt** for global services.
+- Use **Riverpod** for feature-specific providers.
+
+Example:
+```dart
+final GetIt getIt = GetIt.instance;
+Future<void> setupServiceLocator() async {
+  providerContainer = ProviderContainer();
+  getIt
+    ..registerLazySingleton(() => Logger())
+    ..registerLazySingleton(() => FirebaseAuth.instance);
+  // More registrations...
+}
+```
+
+### Routing
+
+- Use GoRouter for declarative, type-safe navigation.
+- Define routes in a centralized file.
+
+Example:
+```dart
+final router = GoRouter(
+  navigatorKey: _rootNavigatorKey,
+  initialLocation: AppRoutes.initialRoute,
+  routes: [
+    ShellRoute(
+      navigatorKey: _shellNavigatorKey,
+      builder: (context, state, child) => BottomNavBar(child: child),
+      routes: [
+        GoRoute(
+          path: AppRoutes.homeRoute,
+          builder: (context, state) => const HomeScreen(),
+        ),
+        // More routes...
+      ],
+    ),
+    // More top-level routes...
+  ],
+);
+```
+
+### Localization
+
+- Use ARB files in `/l10n/` for translations.
+- Support multiple languages (e.g., en, de, ru, tr, ar).
+- Use codegen and scripts to manage translations.
+
+Example:
+```dart
+MaterialApp.router(
+  // ...
+  locale: locale,
+  localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
+    AppLocalizations.delegate,
+    GlobalMaterialLocalizations.delegate,
+    GlobalWidgetsLocalizations.delegate,
+    GlobalCupertinoLocalizations.delegate,
+  ],
+  supportedLocales: const [
+    Locale('en'),
+    Locale('de'),
+    Locale('ru'),
+    Locale('tr'),
+    Locale('ar'),
+  ],
+  // ...
+)
+```
+
+---
+
+## 5. Layered Architecture
+
+- **core/**: Shared utilities, themes, localization, providers, base widgets.
+- **data/**: Data sources, DTOs, mappers, repository implementations.
+- **domain/**: Entities, repository interfaces, usecases.
+- **views/**: Feature modules, each with providers, screens, widgets.
+- **l10n/**: Localization files and scripts.
+- **assets/**: Images, icons, fonts, translations.
+
+---
+
+## 6. State Management with Riverpod (with Annotations)
+
+- Use `@riverpod` annotation for providers.
+- Organize providers by feature.
+
+Example:
+```dart
+@Riverpod(keepAlive: true)
+class EventDetailsNotifier extends _$EventDetailsNotifier {
+  late final EventRepository _eventRepository = getIt<EventRepository>();
+
+  @override
+  EventDetailsState build({required String eventId}) {
+    return EventDetailsState(eventId: eventId);
+  }
+
+  Future<void> loadEventDetails() async {
+    state = state.copyWith(isLoading: true, hasError: false);
+    try {
+      final event = await _eventRepository.getEventById(state.eventId);
+      // ...
+      state = state.copyWith(
+        isLoading: false,
+        hasError: false,
+        event: event,
+        travelInfo: travelInfo,
+      );
+    } catch (e) {
+      state = state.copyWith(
+        isLoading: false,
+        hasError: true,
+        errorMessage: e.toString(),
+      );
+    }
+  }
+}
+```
+
+---
+
+## 7. Model Generation
+
+- Use `freezed` for immutable models and state classes.
+- Use `json_serializable` for JSON (de)serialization.
+
+Example:
+```dart
+@freezed
+class User with _$User {
+  const factory User({
+    required String id,
+    required String email,
+    // ...
+  }) = _User;
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+```
+
+---
+
+## 8. Data Layer Example
+
+- **DTOs**: Data Transfer Objects for serialization.
+- **Mappers**: Transform between DTOs and domain models.
+- **Repositories**: Implement data access logic.
+
+Example DTO:
+```dart
+@freezed
+abstract class EventDTO with _$EventDTO {
+  factory EventDTO({
+    required String id,
+    required String title,
+    // ...
+  }) = _EventDTO;
+  factory EventDTO.fromJson(Map<String, dynamic> json) => _$EventDTOFromJson(json);
+}
+```
+
+Example Mapper:
+```dart
+class EventMapper {
+  static Event toDomain(EventDTO dto) => Event(
+    id: dto.id,
+    title: dto.title,
+    // ...
+  );
+  static EventDTO fromDomain(Event domain) {
+    // ...
+  }
+}
+```
+
+---
+
+## 9. UI Layer Example
+
+- **Screens**: Full-page UI components, handle user interactions.
+- **Widgets**: Reusable UI components.
+- **Providers**: State management for UI.
+
+Example screen:
+```dart
+class EventDetailsScreen extends ConsumerStatefulWidget {
+  final String eventId;
+  const EventDetailsScreen({required this.eventId, super.key});
+  @override
+  ConsumerState<EventDetailsScreen> createState() => _EventDetailsScreenState();
+}
+
+class _EventDetailsScreenState extends ConsumerState<EventDetailsScreen> {
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      ref.read(eventDetailsNotifierProvider(eventId: widget.eventId).notifier)
+        .loadEventDetails();
+    });
+  }
+  @override
+  Widget build(BuildContext context) {
+    final state = ref.watch(eventDetailsNotifierProvider(eventId: widget.eventId));
+    if (state.isLoading) return EventDetailsShimmer();
+    if (state.hasError) return ErrorView(message: state.errorMessage);
+    final event = state.event;
+    if (event == null) return NotFoundView();
+    return DetailScaffold(
+      title: event.title,
+      body: Column(
+        children: [
+          EventOrganizerSection(event: event),
+          EventActionButtons(event: event),
+        ],
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 10. Theming (Dark/Light Mode)
+
+- Define themes in `/core/theme/`.
+- Provide theme switching via Riverpod provider.
+- Use `ThemeMode.system` as default.
+
+---
+
+## 11. CI/CD & Fastlane
+
+- **GitHub Actions:** for static analysis, tests, build, deploy.
+- **Fastlane:** for iOS/Android build & release automation.
+- Example workflow: `.github/workflows/flutter.yml`
+- Fastlane setup in `/fastlane/` ([Fastlane docs](https://docs.fastlane.tools/getting-started/ios/setup/)).
+
+---
+
+## 12. Example pubspec.yaml (excerpt)
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+  riverpod: ^3.0.0
+  flutter_riverpod: ^3.0.0
+  riverpod_annotation: ^3.0.0
+  go_router: ^13.0.0
+  freezed_annotation: ^2.4.1
+  json_serializable: ^6.7.1
+  intl: ^0.18.1
+  flex_color_scheme: ^7.3.1
+  dio: ^5.4.0
+  shared_preferences: ^2.2.2
+  flutter_svg: ^2.0.9
+  cached_network_image: ^3.3.1
+  equatable: ^2.0.5
+dev_dependencies:
+  riverpod_generator: ^3.0.0
+  build_runner: ^2.4.7
+  freezed: ^2.4.6
+  flutter_test:
+    sdk: flutter
+  very_good_analysis: ^5.1.0
+```
+
+---
+
+## 13. Additional Settings
+
+- `analysis_options.yaml` for linting.
+- `.env` for environment variables (use `flutter_dotenv` if needed).
+- README with setup, build, and contribution instructions.
+
+---
+
+## 14. How to Use
+
+- Use this structure as your base.
+- Scaffold folders/files as per above.
+- Add features by duplicating the feature folder pattern.
+- Use Riverpod for all state management.
+- Generate models and providers with build_runner.
+- Add translations in `/l10n/`.
+- Set up CI/CD and Fastlane as per documentation.
+
+---
+
+## 15. Best Practices & Notes
+
+- Keep features modular and isolated.
+- Use code generation to reduce boilerplate.
+- Centralize routing and localization configuration.
+- Prefer immutable state (freezed) and pure functions in domain/usecases.
+- Write tests for all business logic and UI flows.
+- Document your code and keep this architecture file up-to-date.