@rashidee/co2 1.2.5

package/plugin/skills/specgen-flutter-riverpod/references/routing-patterns.md

@@ -0,0 +1,362 @@
+# Routing Patterns — go_router 14 + Feature-Based Architecture
+
+This reference describes the go_router conventions and feature-based directory
+structure used in the spec. Include this content in Sections 4 and 7 of the generated
+specification.
+
+---
+
+## Feature-Based Directory Structure
+
+Each PRD module maps to a `lib/features/<module>/` folder. This co-locates everything
+related to a feature (model, data, application, presentation) so the coding agent can
+implement one feature folder at a time.
+
+```
+lib/
+├── main.dart                              # App entry — Firebase, Hive, Riverpod scope
+├── app.dart                               # MaterialApp.router + theme + locale
+├── firebase_options.dart                  # Generated by `flutterfire configure`
+├── router/
+│   └── app_router.dart                    # go_router configuration + guards
+├── core/
+│   ├── api/
+│   │   ├── dio_provider.dart              # Dio + interceptors
+│   │   ├── api_failure.dart               # Sealed failure type
+│   │   ├── auth_interceptor.dart          # Bearer token injector
+│   │   └── paginated_response.dart        # Generic page envelope
+│   ├── auth/
+│   │   ├── auth_repository.dart           # signIn/signOut/refresh
+│   │   ├── auth_provider.dart             # Riverpod auth state
+│   │   ├── auth_state.dart                # @freezed AuthState
+│   │   └── roles.dart                     # Role constants
+│   ├── local_storage/
+│   │   ├── hive_setup.dart                # Hive.initFlutter + adapters
+│   │   ├── secure_storage_provider.dart   # flutter_secure_storage
+│   │   └── box_provider.dart              # Typed Box providers
+│   ├── notification/
+│   │   ├── notification_service.dart      # FCM + flutter_local_notifications
+│   │   ├── notification_handler.dart      # Foreground/background/tap
+│   │   └── notification_navigation.dart   # Deep-link routing
+│   ├── theme/
+│   │   ├── app_theme.dart
+│   │   ├── app_colors.dart
+│   │   └── app_typography.dart
+│   ├── env/
+│   │   └── env_config.dart
+│   └── utils/
+│       ├── validators.dart
+│       ├── formatters.dart
+│       └── url_helper.dart
+├── shared/
+│   ├── widgets/
+│   │   ├── app_scaffold.dart
+│   │   ├── loading_indicator.dart
+│   │   ├── empty_state.dart
+│   │   ├── error_state.dart
+│   │   ├── confirm_dialog.dart
+│   │   ├── status_chip.dart
+│   │   ├── search_bar_field.dart
+│   │   ├── pull_to_refresh_list.dart
+│   │   ├── infinite_scroll_list.dart
+│   │   ├── app_network_image.dart
+│   │   ├── cached_svg_icon.dart
+│   │   └── shell_screen.dart              # Bottom-nav shell
+│   ├── form/
+│   │   ├── form_text_field.dart
+│   │   ├── form_dropdown_field.dart
+│   │   ├── form_date_picker_field.dart
+│   │   ├── form_switch_field.dart
+│   │   └── form_image_picker_field.dart   # [If ImagePicker = yes]
+│   ├── navigation/
+│   │   └── nav_config.dart                # NavItem list
+│   └── providers/
+│       └── theme_mode_provider.dart       # ThemeMode controller (Hive-backed)
+├── features/
+│   ├── auth/                              # [If Auth != none]
+│   │   ├── presentation/
+│   │   │   ├── login_screen.dart          # [If Auth = Local]
+│   │   │   └── auth_callback_screen.dart  # [If Auth = Keycloak]
+│   │   └── auth.dart                      # Barrel
+│   ├── dashboard/
+│   │   ├── presentation/
+│   │   │   └── dashboard_screen.dart
+│   │   └── dashboard.dart
+│   ├── {{module1}}/                       # PRD module 1 (e.g., task)
+│   │   ├── data/
+│   │   │   └── {{module1}}_repository.dart
+│   │   ├── domain/
+│   │   │   └── {{module1}}.dart           # @freezed + Hive adapter
+│   │   ├── application/
+│   │   │   └── {{module1}}_providers.dart # Generated providers
+│   │   ├── presentation/
+│   │   │   ├── {{module1}}_list_screen.dart
+│   │   │   ├── {{module1}}_detail_screen.dart
+│   │   │   ├── {{module1}}_form_screen.dart
+│   │   │   └── widgets/
+│   │   │       └── {{module1}}_card.dart
+│   │   └── {{module1}}.dart               # Barrel
+│   └── {{module2}}/
+│       └── (same structure)
+└── l10n/                                  # [If i18n = yes]
+    ├── app_en.arb
+    └── app_ms.arb
+```
+
+---
+
+## Route Tree Definition
+
+```dart
+// lib/router/app_router.dart
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+import 'package:riverpod_annotation/riverpod_annotation.dart';
+
+import '../core/auth/auth_provider.dart';
+import '../core/auth/auth_state.dart';
+import '../core/auth/roles.dart';
+import '../features/auth/presentation/auth_callback_screen.dart';
+import '../features/auth/presentation/login_screen.dart';
+import '../features/dashboard/presentation/dashboard_screen.dart';
+import '../features/profile/presentation/profile_screen.dart';
+import '../features/task/presentation/task_form_screen.dart';
+import '../features/task/presentation/task_list_screen.dart';
+import '../shared/widgets/shell_screen.dart';
+
+part 'app_router.g.dart';
+
+@Riverpod(keepAlive: true)
+GoRouter appRouter(AppRouterRef ref) {
+  final authState = ref.watch(authProvider);
+
+  return GoRouter(
+    initialLocation: '/dashboard',
+    debugLogDiagnostics: true,
+    redirect: (context, state) {
+      final isAuthed = authState.valueOrNull is _Authenticated;
+      final atLogin = state.matchedLocation == '/login' ||
+                      state.matchedLocation.startsWith('/auth/');
+
+      // [If Auth = Local]
+      if (!isAuthed && !atLogin) return '/login';
+      if (isAuthed && atLogin) return '/dashboard';
+      return null;
+    },
+    routes: [
+      // ── Auth routes (public) ───────────────────────────────────────────
+      // [If Auth = Local]
+      GoRoute(
+        path: '/login',
+        name: 'login',
+        builder: (context, state) => const LoginScreen(),
+      ),
+      // [If Auth = Keycloak]
+      GoRoute(
+        path: '/auth/callback',
+        name: 'auth-callback',
+        builder: (context, state) => const AuthCallbackScreen(),
+      ),
+
+      // ── Authenticated shell (bottom navigation) ────────────────────────
+      ShellRoute(
+        builder: (context, state, child) => ShellScreen(child: child),
+        routes: [
+          GoRoute(
+            path: '/dashboard',
+            name: 'dashboard',
+            builder: (context, state) => const DashboardScreen(),
+          ),
+
+          // Task — accessible by WORKER and ADMIN
+          GoRoute(
+            path: '/task',
+            name: 'task-list',
+            redirect: (context, state) =>
+                _requireRoles(authState, [Roles.worker, Roles.admin]),
+            builder: (context, state) => const TaskListScreen(),
+            routes: [
+              GoRoute(
+                path: 'create',
+                name: 'task-create',
+                builder: (context, state) => const TaskFormScreen(),
+              ),
+              GoRoute(
+                path: ':id',
+                name: 'task-detail',
+                builder: (context, state) =>
+                    TaskFormScreen(taskId: state.pathParameters['id']),
+                routes: [
+                  GoRoute(
+                    path: 'edit',
+                    name: 'task-edit',
+                    builder: (context, state) =>
+                        TaskFormScreen(taskId: state.pathParameters['id']),
+                  ),
+                ],
+              ),
+            ],
+          ),
+
+          GoRoute(
+            path: '/profile',
+            name: 'profile',
+            builder: (context, state) => const ProfileScreen(),
+          ),
+
+          // Add additional module routes following the same pattern...
+        ],
+      ),
+
+      // ── Error routes ───────────────────────────────────────────────────
+      GoRoute(
+        path: '/unauthorized',
+        builder: (context, state) => Scaffold(
+          appBar: AppBar(title: const Text('Unauthorized')),
+          body: const Center(
+            child: Text('You do not have permission to access this page.'),
+          ),
+        ),
+      ),
+    ],
+    errorBuilder: (context, state) => Scaffold(
+      appBar: AppBar(title: const Text('Not Found')),
+      body: const Center(child: Text('404 — Page not found.')),
+    ),
+  );
+}
+
+String? _requireRoles(AsyncValue<AuthState> authState, List<String> requiredRoles) {
+  final state = authState.valueOrNull;
+  if (state is! _Authenticated) return null; // top-level redirect handles auth
+  final hasAny = requiredRoles.any((r) => state.user.roles.contains(r));
+  return hasAny ? null : '/unauthorized';
+}
+```
+
+---
+
+## ShellScreen (Bottom Navigation Shell)
+
+```dart
+// lib/shared/widgets/shell_screen.dart
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+
+import '../../core/auth/auth_provider.dart';
+import '../../core/auth/auth_state.dart';
+import '../navigation/nav_config.dart';
+
+class ShellScreen extends ConsumerWidget {
+  const ShellScreen({super.key, required this.child});
+  final Widget child;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final authState = ref.watch(authProvider);
+    final user = authState.valueOrNull is _Authenticated
+        ? (authState.value! as _Authenticated).user
+        : null;
+
+    final visibleItems = navigationItems.where((item) {
+      if (item.requiredRoles == null) return true;
+      if (user == null) return false;
+      return item.requiredRoles!.any(user.roles.contains);
+    }).toList();
+
+    final location = GoRouterState.of(context).matchedLocation;
+    final currentIndex = visibleItems.indexWhere(
+      (item) => location.startsWith(item.path),
+    );
+
+    return Scaffold(
+      body: child,
+      bottomNavigationBar: NavigationBar(
+        selectedIndex: currentIndex < 0 ? 0 : currentIndex,
+        onDestinationSelected: (index) => context.go(visibleItems[index].path),
+        destinations: [
+          for (final item in visibleItems)
+            NavigationDestination(
+              icon: Icon(item.icon),
+              selectedIcon: Icon(item.activeIcon),
+              label: item.label,
+            ),
+        ],
+      ),
+    );
+  }
+}
+```
+
+---
+
+## Deep Link Configuration
+
+go_router automatically handles deep links registered in the Android manifest and iOS
+`Info.plist`. For FCM notification payloads, use the same path structure.
+
+**Notification payload example:**
+```json
+{
+  "notification": {
+    "title": "New task assigned",
+    "body": "Inspect site #42"
+  },
+  "data": {
+    "deeplink": "/task/abc-123"
+  }
+}
+```
+
+**Handler (in `NotificationService`):**
+```dart
+FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
+  final deeplink = message.data['deeplink'] as String?;
+  if (deeplink != null) {
+    // Read router from ProviderContainer at app root (set up in app.dart)
+    rootContainer.read(appRouterProvider).go(deeplink);
+  }
+});
+```
+
+---
+
+## Typed Route Helpers (Optional via go_router_builder)
+
+If `go_router_builder` is added, define typed route classes for compile-time safety:
+
+```dart
+@TypedGoRoute<TaskDetailRoute>(path: '/task/:id')
+class TaskDetailRoute extends GoRouteData {
+  const TaskDetailRoute({required this.id});
+  final String id;
+
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      TaskFormScreen(taskId: id);
+}
+
+// Navigate:
+// TaskDetailRoute(id: 'abc-123').push(context);
+```
+
+---
+
+## AppBar Back Behaviour
+
+go_router handles back gestures and the AppBar back arrow automatically via
+`canPop()`. Inside a `ShellRoute`, prefer `context.go(<parent>)` over `context.pop()`
+when navigating between top-level tabs.
+
+---
+
+## Route Guards Summary
+
+| Guard | Location | Behaviour |
+|---|---|---|
+| Auth required | Top-level `GoRouter.redirect` | Push `/login` when unauthenticated |
+| Role required | Per-route `redirect` callback | Push `/unauthorized` when role missing |
+| Onboarding | Top-level `GoRouter.redirect` | Push `/onboarding` on first launch (Hive flag) |
+| Deep link from FCM | `NotificationService.onMessageOpenedApp` | Push payload `deeplink` via router instance |