Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update mobile development guidelines to enforce safe navigation and typed navigators with fallback mechanisms.

Browse Source
This commit is contained in:
Achintha Isuru
2026-02-28 17:57:40 -05:00
parent 6902e84519
commit d3f3b0f70e
3 changed files with 13 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/MOBILE/00-agent-development-rules.md
View File

@@ -42,9 +42,10 @@ Follow Dart standards strictly.
* **Data Transformation**: MUST reside in **Repositories** (Data Connect layer). * **Data Transformation**: MUST reside in **Repositories** (Data Connect layer).
* *Forbidden*: Parsing JSON in the UI or Domain. * *Forbidden*: Parsing JSON in the UI or Domain.
* **Pattern**: Repositories map Data Connect models to Domain entities. * **Pattern**: Repositories map Data Connect models to Domain entities.
* **Navigation Logic**: MUST reside in **Flutter Modular Routes**. * **Navigation Logic**: MUST reside in **Flutter Modular Routes** and use **Safe Navigation**.
* *Forbidden*: `Navigator.push` with hardcoded widgets. * *Forbidden*: `Navigator.push` with hardcoded widgets or direct `Modular.to.pop()` / `Modular.to.navigate()`.
* **Pattern**: Use named routes via `Modular.to.navigate()`. * **Pattern**: Use `popSafe()`, `safeNavigate()`, `safePush()`, etc., from `NavigationExtensions`. Prefer **Typed Navigators** (e.g., `Modular.to.toHome()`).
* **Fallback**: All navigation MUST have a fallback to the Home page implemented in `NavigationExtensions`.
* **Session Management**: MUST reside in **DataConnectService** via **SessionHandlerMixin**. * **Session Management**: MUST reside in **DataConnectService** via **SessionHandlerMixin**.
* **Pattern**: Automatic token refresh, auth state listening, and role-based validation. * **Pattern**: Automatic token refresh, auth state listening, and role-based validation.
* **UI Reaction**: **SessionListener** widget wraps the entire app and responds to session state changes. * **UI Reaction**: **SessionListener** widget wraps the entire app and responds to session state changes.

8
docs/MOBILE/01-architecture-principles.md
View File

@@ -178,9 +178,11 @@ All backend access is unified through `DataConnectService` with integrated sessi
- **Zero Direct Imports**: `import 'package:feature_a/...'` is FORBIDDEN inside `package:feature_b`. - **Zero Direct Imports**: `import 'package:feature_a/...'` is FORBIDDEN inside `package:feature_b`.
- Exception: Shared packages like `domain`, `core`, and `design_system` are always accessible. - Exception: Shared packages like `domain`, `core`, and `design_system` are always accessible.
- **Navigation**: Use named routes via Flutter Modular: - **Navigation**: Use **Typed Navigators** and **Safe Navigation** via Flutter Modular:
- **Pattern**: `Modular.to.navigate('route_name')` - **Safe Methods**: ALWAYS use `safeNavigate()`, `safePush()`, `popSafe()`, and `safePushNamedAndRemoveUntil()` from `NavigationExtensions`.
- **Configuration**: Routes defined in `module.dart` files; constants in `paths.dart` - **Fallback**: All safe methods automatically fall back to the Home page (Staff or Client) if the target route is invalid or the operation fails.
- **Typed Navigator Pattern**: Prefer using typed methods on `Modular.to` (e.g., `Modular.to.toShiftDetails(id)`) which are implemented in `ClientNavigator` and `StaffNavigator` using these safe extensions.
- **Configuration**: Routes defined in `module.dart` files; constants in `paths.dart`.
- **Data Sharing**: Features do not share state directly. Shared data accessed through: - **Data Sharing**: Features do not share state directly. Shared data accessed through:
- **Domain Repositories**: Centralized data sources (e.g., `AuthRepository`) - **Domain Repositories**: Centralized data sources (e.g., `AuthRepository`)
- **Session Stores**: `StaffSessionStore` and `ClientSessionStore` for app-wide user context - **Session Stores**: `StaffSessionStore` and `ClientSessionStore` for app-wide user context

6
docs/MOBILE/02-design-system-usage.md
View File

@@ -1,4 +1,4 @@
# 03 - Design System Usage Guide # 02 - Design System Usage Guide
This document defines the mandatory standards for designing and implementing user interfaces across all applications and feature packages using the shared `apps/mobile/packages/design_system`. This document defines the mandatory standards for designing and implementing user interfaces across all applications and feature packages using the shared `apps/mobile/packages/design_system`.
@@ -88,7 +88,9 @@ Padding(
The design system provides "Smart Widgets" – these are high-level UI components that encapsulate both styling and standard behavior. The design system provides "Smart Widgets" – these are high-level UI components that encapsulate both styling and standard behavior.
- **Standard Widgets**: Prefer standard Flutter Material widgets (e.g., `ElevatedButton`) but styled via the central theme. - **Standard Widgets**: Prefer standard Flutter Material widgets (e.g., `ElevatedButton`) but styled via the central theme.
- **Custom Components**: Use `design_system` widgets for non-standard elements or wisgets that has similar design across various features, if provided. - **Custom Components**: Use `design_system` widgets for non-standard elements or widgets that have similar design across various features, if provided.
- **Navigation in Widgets**: Widgets that trigger navigation (e.g., Back buttons in `UiAppBar`) MUST use `Modular.to.popSafe()` or typed navigator methods to prevent blank screens or unexpected application states during stack pops.
- **Composition**: Prefer composing standard widgets over creating deep inheritance hierarchies in features. - **Composition**: Prefer composing standard widgets over creating deep inheritance hierarchies in features.
## 9. Theme Configuration & Usage ## 9. Theme Configuration & Usage