devendra-skill-package 1.0.2

package/.github/skills/clean-architecture-generator/references/platform-flutter.md

@@ -0,0 +1,366 @@
+# Platform File — Flutter
+
+Read `architecture-core.md` first. Flutter differs from the other three platforms in language
+(Dart, not TypeScript) and in file-naming convention — Dart's own style guide (Effective Dart) is
+the authority here, not the RN/React/Angular conventions in the other platform files.
+
+Everything under "Stack Fingerprint Defaults" applies **only** when Phase 1 detection found nothing
+in `pubspec.yaml` / existing feature code in the target repo.
+
+---
+
+## Stack Fingerprint Defaults (greenfield only)
+
+| Concern | Detect first (search `pubspec.yaml` dependencies + existing code) | Default if nothing detected |
+|---|---|---|
+| State management | `flutter_riverpod`/`hooks_riverpod` (Riverpod), `flutter_bloc` (Bloc/Cubit), `provider` package, `get` (GetX) | `flutter_bloc` (Bloc for complex event-driven state, or its `Cubit` subset for simpler feature state) |
+| DI mechanism | `get_it`, Riverpod's own provider graph (if Riverpod is the detected state lib, its providers also serve as DI — do not add `get_it` on top), `injectable` codegen | `get_it` — lazy singleton service locator (see DI Pattern below) |
+| HTTP client | `Dio(`, `package:http/http.dart`, `chopper`, `retrofit` annotations | `dio` with interceptors |
+| Local storage | `shared_preferences`, `flutter_secure_storage`, `hive`, `sqflite`, `drift` | `flutter_secure_storage` for tokens/secrets, `shared_preferences` for non-sensitive prefs |
+| Navigation | `go_router`, `auto_route`, raw `Navigator.push`/`Navigator.of(context).push` | `go_router` |
+| Functional error handling | `dartz` / `fpdart` `Either<Failure, T>` return types on repository methods | plain `Future<T>` that throws a typed `Exception`/`Failure` — only introduce `Either` if the project already uses it, since it's a deliberate, project-wide functional-style choice, not a default to impose |
+| Test runner | — | `flutter_test` + `mocktail`/`mockito` for mocks (whichever is already in `pubspec.yaml` dev_dependencies) |
+
+---
+
+## Folder Tree
+
+```
+lib/
+├── main.dart
+├── app/
+│   ├── app.dart                      # MaterialApp.router root widget
+│   ├── di/
+│   │   └── injection_container.dart  # get_it registrations, called once from main()
+│   └── routing/
+│       └── app_router.dart           # go_router configuration, mounts each feature's routes
+│
+├── core/                              # Infrastructure — shared by all features
+│   ├── network/
+│   │   ├── dio_client.dart            # Singleton Dio instance + interceptors
+│   │   └── network_info.dart          # connectivity_plus wrapper
+│   ├── error/
+│   │   ├── failures.dart              # sealed Failure hierarchy
+│   │   └── exceptions.dart
+│   ├── storage/
+│   │   ├── secure_storage_service.dart
+│   │   └── shared_prefs_service.dart
+│   ├── usecase/
+│   │   └── usecase.dart               # abstract UseCase<Type, Params> base class
+│   └── theme/
+│       └── app_theme.dart
+│
+├── features/
+│   └── [feature_name]/                 # snake_case folder — see Naming Extensions
+│       ├── domain/                     # Pure Dart — ZERO Flutter/Dio/state-lib imports
+│       │   ├── entities/
+│       │   │   └── [item]_entity.dart
+│       │   ├── repositories/
+│       │   │   └── [feature]_repository.dart      # abstract class, no `I` prefix
+│       │   └── usecases/
+│       │       └── get_[item]_usecase.dart
+│       ├── data/
+│       │   ├── models/                             # DTOs — Flutter convention calls these "Models"
+│       │   │   └── [item]_model.dart
+│       │   ├── datasources/
+│       │   │   └── [feature]_remote_data_source.dart
+│       │   └── repositories/
+│       │       └── [feature]_repository_impl.dart
+│       ├── presentation/
+│       │   ├── pages/
+│       │   │   └── [feature]_page.dart
+│       │   ├── widgets/
+│       │   └── bloc/                                # or riverpod/ or provider/ — matches detected state lib
+│       │       ├── [feature]_bloc.dart
+│       │       ├── [feature]_event.dart
+│       │       └── [feature]_state.dart
+│       └── [feature]_injection.dart                  # get_it registrations for this feature only
+│
+└── shared/
+    └── widgets/                        # Reusable presentational widgets with no feature dependency
+```
+
+---
+
+## Naming Extensions (Flutter/Dart-specific — Effective Dart, not invented)
+
+Effective Dart specifies **snake_case for file names**, **PascalCase (UpperCamelCase) for class
+names**, and explicitly recommends **against** an `I`-prefix on abstract/interface classes
+("AVOID prefixing interface names with I—just use the plain name"). Follow this exactly — it is
+different from the RN/React `I`-prefix convention and must not be mixed in:
+
+| Artifact | Convention | Example |
+|----------|------------|---------|
+| Feature folder | snake_case | `portfolio_summary`, `user_profile` |
+| Entity file | snake_case + `_entity.dart` | `holding_entity.dart` (class `HoldingEntity`) |
+| Repository abstraction | snake_case + `_repository.dart`, **no `I` prefix** | `holding_repository.dart` (abstract class `HoldingRepository`) |
+| Repository implementation | snake_case + `_repository_impl.dart` | `holding_repository_impl.dart` (class `HoldingRepositoryImpl`) |
+| Use case file | snake_case + `_usecase.dart` | `get_holding_summary_usecase.dart` (class `GetHoldingSummaryUseCase`) |
+| Model/DTO file | snake_case + `_model.dart` | `holding_summary_model.dart` (class `HoldingSummaryModel`) |
+| Mapper | a `toEntity()` method on the Model, or a top-level `mapTo…` function — see Data Layer Pattern | `HoldingSummaryModel.toEntity()` |
+| Remote data source | snake_case + `_remote_data_source.dart` | `holding_remote_data_source.dart` |
+| Page/widget file | snake_case + `_page.dart` / `_widget.dart` | `holding_detail_page.dart` |
+| Bloc files | snake_case + `_bloc.dart` / `_event.dart` / `_state.dart` | `holding_bloc.dart` |
+| Riverpod provider file (if Riverpod detected) | snake_case + `_provider.dart` | `holding_provider.dart` |
+| DI registration file | snake_case + `_injection.dart` | `holding_injection.dart` |
+| Test file | mirrors source path under `test/`, `_test.dart` suffix | `holding_repository_impl_test.dart` |
+| Loading/state status | a sealed class or enum with explicit named states (`Initial`, `Loading`, `Success`, `Failure`) | never a raw `bool isLoading` on a Bloc/Cubit state |
+
+---
+
+## DI Pattern — `get_it` Lazy Service Locator (default when nothing else detected)
+
+```dart
+// features/[feature_name]/[feature]_injection.dart
+import 'package:get_it/get_it.dart';
+import '../../core/network/dio_client.dart';
+import 'data/datasources/[feature]_remote_data_source.dart';
+import 'data/repositories/[feature]_repository_impl.dart';
+import 'domain/repositories/[feature]_repository.dart';
+import 'domain/usecases/get_[item]_usecase.dart';
+
+final sl = GetIt.instance;
+
+void init[Feature]Dependencies() {
+  sl.registerLazySingleton<[Feature]RemoteDataSource>(
+    () => [Feature]RemoteDataSourceImpl(sl<DioClient>()),
+  );
+  sl.registerLazySingleton<[Feature]Repository>(
+    () => [Feature]RepositoryImpl(sl<[Feature]RemoteDataSource>()),
+  );
+  sl.registerFactory<Get[Item]UseCase>(
+    () => Get[Item]UseCase(sl<[Feature]Repository>()),
+  );
+}
+```
+
+Call `init[Feature]Dependencies()` once from `app/di/injection_container.dart`'s top-level `init()`,
+which itself runs once in `main()` before `runApp()`.
+
+**If Riverpod is detected** in the target repo, do not add `get_it` on top of it — Riverpod's own
+provider graph already serves this role. Express the same wiring as providers instead:
+
+```dart
+// features/[feature_name]/domain/repositories/[feature]_repository.dart
+final [feature]RepositoryProvider = Provider<[Feature]Repository>(
+  (ref) => [Feature]RepositoryImpl(ref.watch(dioClientProvider)),
+);
+```
+
+## Domain Layer Pattern
+
+```dart
+// domain/repositories/[feature]_repository.dart
+import '../entities/[item]_entity.dart';
+
+abstract class [Feature]Repository {
+  Future<[Item]Entity> get[Item]([RequestArgs] args);
+}
+
+// domain/usecases/get_[item]_usecase.dart
+import '../entities/[item]_entity.dart';
+import '../repositories/[feature]_repository.dart';
+
+class Get[Item]UseCase {
+  final [Feature]Repository repository;
+  Get[Item]UseCase(this.repository);
+
+  Future<[Item]Entity> call([RequestArgs] args) => repository.get[Item](args);
+}
+```
+
+Note the `call()` method convention: Dart classes with a single `call()` method can be invoked like
+a function (`get[Item]UseCase(args)`), which is the idiomatic Flutter clean-architecture equivalent
+of the RN/React `.execute(args)` method name. Use `call()`, not `execute()`, for Flutter use cases.
+
+## Data Layer Pattern
+
+```dart
+// data/models/[item]_model.dart
+import '../../domain/entities/[item]_entity.dart';
+
+class [Item]Model {
+  final String id;
+  // ...other raw fields exactly as the API returns them
+
+  [Item]Model({required this.id});
+
+  factory [Item]Model.fromJson(Map<String, dynamic> json) =>
+      [Item]Model(id: json['id'] as String);
+
+  [Item]Entity toEntity() => [Item]Entity(id: id);
+}
+
+// data/datasources/[feature]_remote_data_source.dart
+import '../../../../core/network/dio_client.dart';
+import '../models/[item]_model.dart';
+
+abstract class [Feature]RemoteDataSource {
+  Future<[Item]Model> get[Item]([RequestArgs] args);
+}
+
+class [Feature]RemoteDataSourceImpl implements [Feature]RemoteDataSource {
+  final DioClient dioClient;
+  [Feature]RemoteDataSourceImpl(this.dioClient);
+
+  @override
+  Future<[Item]Model> get[Item]([RequestArgs] args) async {
+    final response = await dioClient.dio.post('/[endpoint]', data: args.toJson());
+    return [Item]Model.fromJson(response.data);
+  }
+}
+
+// data/repositories/[feature]_repository_impl.dart
+import '../../domain/entities/[item]_entity.dart';
+import '../../domain/repositories/[feature]_repository.dart';
+import '../datasources/[feature]_remote_data_source.dart';
+
+class [Feature]RepositoryImpl implements [Feature]Repository {
+  final [Feature]RemoteDataSource remoteDataSource;
+  [Feature]RepositoryImpl(this.remoteDataSource);
+
+  @override
+  Future<[Item]Entity> get[Item]([RequestArgs] args) async {
+    final model = await remoteDataSource.get[Item](args);
+    return model.toEntity();
+  }
+}
+```
+
+## Presentation Layer Pattern — Bloc (default when nothing else detected)
+
+```dart
+// presentation/bloc/[feature]_event.dart
+sealed class [Feature]Event {}
+class Fetch[Item]Requested extends [Feature]Event {
+  final [RequestArgs] args;
+  Fetch[Item]Requested(this.args);
+}
+
+// presentation/bloc/[feature]_state.dart
+sealed class [Feature]State {}
+class [Feature]Initial extends [Feature]State {}
+class [Feature]Loading extends [Feature]State {}
+class [Feature]Success extends [Feature]State {
+  final [Item]Entity data;
+  [Feature]Success(this.data);
+}
+class [Feature]Failure extends [Feature]State {
+  final String message;
+  [Feature]Failure(this.message);
+}
+
+// presentation/bloc/[feature]_bloc.dart
+import 'package:flutter_bloc/flutter_bloc.dart';
+import '../../domain/usecases/get_[item]_usecase.dart';
+import '[feature]_event.dart';
+import '[feature]_state.dart';
+
+class [Feature]Bloc extends Bloc<[Feature]Event, [Feature]State> {
+  final Get[Item]UseCase get[Item]UseCase;
+
+  [Feature]Bloc(this.get[Item]UseCase) : super([Feature]Initial()) {
+    on<Fetch[Item]Requested>((event, emit) async {
+      emit([Feature]Loading());
+      try {
+        final data = await get[Item]UseCase(event.args);
+        emit([Feature]Success(data));
+      } catch (e) {
+        emit([Feature]Failure(e.toString()));
+      }
+    });
+  }
+}
+```
+
+Widget consumes via `BlocProvider`/`BlocBuilder` — never call the use case or repository directly
+from a widget's `build()` method.
+
+**If Riverpod, Provider, or GetX is detected**, use that project's existing pattern instead of Bloc
+— follow the same `presentation/[state-lib-name]/` subfolder convention shown in the folder tree,
+and do not introduce a second state-management library alongside the existing one.
+
+## Routing Pattern — `go_router` (default when nothing else detected)
+
+```dart
+// app/routing/app_router.dart
+import 'package:go_router/go_router.dart';
+import '../../features/[feature_name]/presentation/pages/[feature]_page.dart';
+
+final appRouter = GoRouter(
+  routes: [
+    GoRoute(
+      path: '/[feature]',
+      builder: (context, state) => const [Feature]Page(),
+      routes: [
+        GoRoute(
+          path: ':id',
+          builder: (context, state) => [Feature]DetailPage(id: state.pathParameters['id']!),
+        ),
+      ],
+    ),
+  ],
+);
+```
+
+`app/app.dart` uses `MaterialApp.router(routerConfig: appRouter)`.
+
+---
+
+## Security Rules (mobile-specific — on top of architecture-core.md)
+
+1. Tokens and other secrets go in `flutter_secure_storage` (backed by Keychain on iOS, EncryptedSharedPreferences/Keystore on Android) — never `shared_preferences`, which stores plaintext.
+2. Certificate pinning (if required) is configured on the `Dio` client's `HttpClientAdapter` — never disable certificate validation (`badCertificateCallback` returning `true` unconditionally) in production code.
+3. Encryption keys are managed via the platform Keychain/Keystore — never embedded as a Dart string constant.
+
+---
+
+## Anti-Patterns (Flutter/Dart-specific, on top of architecture-core.md)
+
+- **Never** call `Dio`/`http` directly from a widget or a Bloc/Cubit event handler — always go through the feature's `[Feature]Repository`.
+- **Never** put business logic inside a widget's `build()` method — it belongs in a use case.
+- **Never** use `dynamic` to avoid modeling a type — use an explicit type or a sealed class.
+- **Never** store tokens or secrets in `shared_preferences` — use `flutter_secure_storage`.
+- **Never** prefix an abstract class with `I` (e.g. `IHoldingRepository`) — Effective Dart forbids
+  Hungarian-notation interface prefixes; use the plain name (`HoldingRepository`).
+- **Never** name a use case's entry method `execute()` — Flutter clean-architecture convention uses
+  `call()` so the use case is invokable like a function.
+- **Never** rebuild an entire widget subtree when only a small piece of state changed — scope
+  `BlocBuilder`/`Consumer`/`Selector` listeners narrowly (`buildWhen`, `select`) instead of wrapping
+  the whole page.
+- **Never** mix two state-management libraries in the same feature (e.g. Bloc for one screen,
+  Riverpod for another in the same feature) — one feature, one state-management approach.
+
+---
+
+## Worked Example
+
+**Request**: "Add a watchlist feature with ability to fetch and display watchlist items."
+
+**Artifacts**:
+- Domain: `watchlist_item_entity.dart` → `WatchlistItemEntity`; `watchlist_repository.dart` (abstract) → `WatchlistRepository`; `get_watchlist_usecase.dart` → `GetWatchlistUseCase`
+- Data: `watchlist_item_model.dart`, `watchlist_remote_data_source.dart`, `watchlist_repository_impl.dart`
+- Presentation: `watchlist_bloc.dart`/`_event.dart`/`_state.dart`, `watchlist_page.dart`
+- DI: `watchlist_injection.dart` (get_it)
+
+**Output**:
+```
+Created:
+  lib/features/watchlist/domain/entities/watchlist_item_entity.dart
+  lib/features/watchlist/domain/repositories/watchlist_repository.dart
+  lib/features/watchlist/domain/usecases/get_watchlist_usecase.dart
+  lib/features/watchlist/data/models/watchlist_item_model.dart
+  lib/features/watchlist/data/datasources/watchlist_remote_data_source.dart
+  lib/features/watchlist/data/repositories/watchlist_repository_impl.dart
+  lib/features/watchlist/presentation/bloc/watchlist_bloc.dart
+  lib/features/watchlist/presentation/bloc/watchlist_event.dart
+  lib/features/watchlist/presentation/bloc/watchlist_state.dart
+  lib/features/watchlist/presentation/pages/watchlist_page.dart
+  lib/features/watchlist/watchlist_injection.dart
+
+Updated:
+  lib/app/di/injection_container.dart   (called initWatchlistDependencies())
+  lib/app/routing/app_router.dart        (added /watchlist route)
+
+Dependency check: PASS — no layer boundary violations detected
+```