Role-Based Route Guard
Component Detail
Description
Integrates with Flutter's StatefulShellRoute and GoRouter to enforce role-based navigation at the routing level. Redirects unauthorized role access to the no-access screen or login, and conditionally builds the navigation shell based on active role.
role-route-guard
Summaries
The Role-Based Route Guard is the enforcement mechanism that ensures users can only access the parts of the application appropriate to their assigned role. Without this component, a user with restricted permissions could navigate to administrative or peer-mentor screens, creating security vulnerabilities and a confusing, error-prone user experience. By redirecting unauthorized access attempts immediately at the navigation level, it reduces support costs associated with permission confusion and protects sensitive workflows from accidental or malicious misuse. This component directly supports the product's ability to serve multiple user types within a single application, a key competitive advantage enabling efficient multi-role deployment without separate app builds.
This is a medium-complexity component with two hard dependencies — role-state-manager and permission-checker — that must be completed and tested before integration work can begin. Schedule this component after those dependencies are stable, as its logic branches on role state that must be fully populated at navigation time. Testing scope is substantial: each role type requires navigation path validation, unauthorized redirect scenarios must be verified, and edge cases like unauthenticated state and role transitions mid-session need coverage. The GoRouter redirect lifecycle introduces timing considerations that may require careful state synchronization.
Regression risk is high when role definitions or route structures change, so integration tests covering all role-route combinations should be maintained as living documentation.
Implemented as a GoRouter redirect callback integrated with Flutter's `StatefulShellRoute`, this component intercepts every navigation event and validates it against the active role from `role-state-manager`. The `redirect` method runs synchronously within GoRouter's redirect pipeline, so role state must be immediately accessible — avoid async calls here; rely on pre-loaded state from the manager. `buildShellBranches(Role activeRole)` dynamically constructs the `StatefulShellRoute` branch list, enabling per-role navigation shells without redundant route declarations. `isRoutePermitted` should delegate to `permission-checker` for consistent permission logic.
Unauthorized redirects should preserve the attempted route in `GoRouterState` for post-authentication deep linking. Watch for re-render loops if role state changes trigger navigation which re-evaluates role state.
Responsibilities
- Intercept navigation events and validate role permissions
- Redirect global admin users to no-access screen
- Build StatefulShellRoute branches conditionally per role
- Handle unauthenticated navigation attempts
Interfaces
redirect(BuildContext context, GoRouterState state)
buildShellBranches(Role activeRole)
isRoutePermitted(Role role, String routePath)
onUnauthorizedAccess(Role role, String route)
Relationships
Dependencies (2)
Components this component depends on