Navigation Shell
Feature Detail
Description
The Navigation Shell provides the foundational app-wide routing and navigation structure for the Likeperson mobile application. It implements a bottom navigation bar with five primary tabs — Home, Contacts, Add, Work, and Notifications — using Flutter's StatefulShellRoute to preserve tab state across navigation events. The shell also integrates a hamburger menu for accessing Settings and secondary destinations, ensuring a consistent and predictable navigation experience across all user roles (admin, coordinator, peer mentor).
Analysis
A stable, well-structured navigation shell is the backbone of the entire application. Without it, no feature is reachable or usable. Preserving tab state is critical for peer mentors who frequently switch between Contacts and the Add tab during field work, preventing data loss and reducing frustration. The role-aware routing ensures that coordinators, admins, and peer mentors each see only the navigation paths relevant to their responsibilities, reducing cognitive load and preventing accidental access to restricted areas. This directly supports the universal design requirement identified across all three organizations.
Implemented using Flutter's go_router package with StatefulShellRoute for branch-based tab navigation and state preservation. The bottom navigation bar is built from design tokens (colors, typography, sizing) to ensure WCAG 2.2 AA contrast compliance. Role-based route guards are applied at the shell level using Riverpod providers that reactively respond to authentication state changes from Supabase. The hamburger menu uses a Drawer widget integrated into the AppBar. Deep link support is configured via go_router for notification-triggered navigation. All navigation transitions are accessible and respect reduced-motion preferences.
Dependencies
Definition of Done
Components (4)
User Stories (21)
As a As a user
I want I want to open a side drawer from the hamburger menu icon in the app bar to access Settings and other secondary destinations
So that So that I can configure my preferences and reach infrequently used sections without cluttering the primary bottom navigation
- Given the user is on any tab, when they tap the hamburger icon in the AppBar, then the Drawer slides in from the left with secondary navigation options including Settings
- Given the Drawer is open, when the user taps 'Settings', then the Drawer closes and the Settings screen is pushed onto the current tab's navigation stack
- Given the Drawer is open, when the user taps outside the Drawer or swipes it closed, then the Drawer closes and the user remains on the current screen
- +2 more
As a As a user
I want I want to open a side drawer from the hamburger menu icon in the app bar to access Settings and other secondary destinations
So that So that I can configure my preferences and reach infrequently used sections without cluttering the primary bottom navigation
- Given the user is on any tab, when they tap the hamburger icon in the AppBar, then the Drawer slides in from the left with secondary navigation options including Settings
- Given the Drawer is open, when the user taps 'Settings', then the Drawer closes and the Settings screen is pushed onto the current tab's navigation stack
- Given the Drawer is open, when the user taps outside the Drawer or swipes it closed, then the Drawer closes and the user remains on the current screen
- +2 more
As a As a user
I want I want to open a side drawer from the hamburger menu icon in the app bar to access Settings and other secondary destinations
So that So that I can configure my preferences and reach infrequently used sections without cluttering the primary bottom navigation
- Given the user is on any tab, when they tap the hamburger icon in the AppBar, then the Drawer slides in from the left with secondary navigation options including Settings
- Given the Drawer is open, when the user taps 'Settings', then the Drawer closes and the Settings screen is pushed onto the current tab's navigation stack
- Given the Drawer is open, when the user taps outside the Drawer or swipes it closed, then the Drawer closes and the user remains on the current screen
- +2 more
As a As a user
I want I want all navigation elements in the bottom bar, app bar, and drawer to be fully operable and clearly announced by VoiceOver and JAWS screen readers
So that So that visually impaired users can independently navigate the full app without assistance
- Given VoiceOver is enabled on iOS, when the user focuses on the bottom navigation bar, then each tab is announced as '[Tab name], tab, [selected/not selected]'
- Given JAWS is active, when the user navigates to the hamburger menu button, then it is announced as 'Open navigation menu, button'
- Given a screen reader is active, when the user activates a tab or drawer item, then the newly displayed screen title is announced immediately upon navigation
- +3 more
As a As a user
I want I want my scroll position, search query, and in-progress form state to be preserved when I switch away from a tab and then return to it
So that So that I do not lose my work or have to re-navigate to the same position after temporarily switching tabs
- Given the user has scrolled partway down a list in a tab, when they switch to another tab and return, then the scroll position is exactly where they left it
- Given the user has entered a search query in the Contacts tab, when they navigate to the Add tab and back, then the search query and filtered results are still visible
- Given the user has an in-progress multi-step wizard open in a tab (e.g., Add), when they switch to Notifications and return, then the wizard is still open at the same step with all entered data intact
- +2 more
As a As a user
I want I want tapping a push notification to bring me directly to the relevant screen in the app (e.g., a new assignment, an approval request, or an expiry alert) without manually navigating through the tab structure
So that So that I can act on time-sensitive information immediately and reduce the steps needed to respond
- Given a peer mentor receives a push notification for a new encrypted assignment, when they tap the notification, then the app opens to the Assignment Detail screen with the correct assignment loaded
- Given a coordinator receives a notification about a pending reimbursement approval, when they tap the notification, then the app navigates to the Reimbursement Detail screen within the Work tab
- Given the app is terminated, when the user taps a push notification, then the app launches, authenticates the user, and then navigates to the deep link destination
- +2 more
As a As a user
I want I want all navigation elements in the bottom bar, app bar, and drawer to be fully operable and clearly announced by VoiceOver and JAWS screen readers
So that So that visually impaired users can independently navigate the full app without assistance
- Given VoiceOver is enabled on iOS, when the user focuses on the bottom navigation bar, then each tab is announced as '[Tab name], tab, [selected/not selected]'
- Given JAWS is active, when the user navigates to the hamburger menu button, then it is announced as 'Open navigation menu, button'
- Given a screen reader is active, when the user activates a tab or drawer item, then the newly displayed screen title is announced immediately upon navigation
- +3 more
As a As a user
I want I want my scroll position, search query, and in-progress form state to be preserved when I switch away from a tab and then return to it
So that So that I do not lose my work or have to re-navigate to the same position after temporarily switching tabs
- Given the user has scrolled partway down a list in a tab, when they switch to another tab and return, then the scroll position is exactly where they left it
- Given the user has entered a search query in the Contacts tab, when they navigate to the Add tab and back, then the search query and filtered results are still visible
- Given the user has an in-progress multi-step wizard open in a tab (e.g., Add), when they switch to Notifications and return, then the wizard is still open at the same step with all entered data intact
- +2 more
As a As a user
I want I want tapping a push notification to bring me directly to the relevant screen in the app (e.g., a new assignment, an approval request, or an expiry alert) without manually navigating through the tab structure
So that So that I can act on time-sensitive information immediately and reduce the steps needed to respond
- Given a peer mentor receives a push notification for a new encrypted assignment, when they tap the notification, then the app opens to the Assignment Detail screen with the correct assignment loaded
- Given a coordinator receives a notification about a pending reimbursement approval, when they tap the notification, then the app navigates to the Reimbursement Detail screen within the Work tab
- Given the app is terminated, when the user taps a push notification, then the app launches, authenticates the user, and then navigates to the deep link destination
- +2 more
As a As a user
I want I want all navigation elements in the bottom bar, app bar, and drawer to be fully operable and clearly announced by VoiceOver and JAWS screen readers
So that So that visually impaired users can independently navigate the full app without assistance
- Given VoiceOver is enabled on iOS, when the user focuses on the bottom navigation bar, then each tab is announced as '[Tab name], tab, [selected/not selected]'
- Given JAWS is active, when the user navigates to the hamburger menu button, then it is announced as 'Open navigation menu, button'
- Given a screen reader is active, when the user activates a tab or drawer item, then the newly displayed screen title is announced immediately upon navigation
- +3 more
As a As a user
I want I want my scroll position, search query, and in-progress form state to be preserved when I switch away from a tab and then return to it
So that So that I do not lose my work or have to re-navigate to the same position after temporarily switching tabs
- Given the user has scrolled partway down a list in a tab, when they switch to another tab and return, then the scroll position is exactly where they left it
- Given the user has entered a search query in the Contacts tab, when they navigate to the Add tab and back, then the search query and filtered results are still visible
- Given the user has an in-progress multi-step wizard open in a tab (e.g., Add), when they switch to Notifications and return, then the wizard is still open at the same step with all entered data intact
- +2 more
As a As a user
I want I want tapping a push notification to bring me directly to the relevant screen in the app (e.g., a new assignment, an approval request, or an expiry alert) without manually navigating through the tab structure
So that So that I can act on time-sensitive information immediately and reduce the steps needed to respond
- Given a peer mentor receives a push notification for a new encrypted assignment, when they tap the notification, then the app opens to the Assignment Detail screen with the correct assignment loaded
- Given a coordinator receives a notification about a pending reimbursement approval, when they tap the notification, then the app navigates to the Reimbursement Detail screen within the Work tab
- Given the app is terminated, when the user taps a push notification, then the app launches, authenticates the user, and then navigates to the deep link destination
- +2 more
As a As a user
I want I want the navigation shell to automatically redirect me to the login screen if my session expires or I log out, and to restore my last active context after I re-authenticate
So that So that my session is always secure and I am never stranded on an authenticated screen without a valid session
- Given a user is authenticated and on any screen, when their Supabase session expires, then the navigation shell automatically redirects to the login screen and clears the authenticated navigation stack
- Given a user taps 'Log out', when the logout action completes, then the navigation stack is fully cleared and the login screen is shown with no back navigation possible to authenticated screens
- Given a user's session expired while they were away from the app, when they return and tap a push notification deep link, then they are shown the login screen first, and after authentication, they are taken to the deep link destination
- +2 more
As a As a user
I want I want to navigate between the five primary sections of the app — Home, Contacts, Add, Work, and Notifications — using the bottom navigation bar
So that So that I can quickly move between core app areas without losing my place or reloading content
- Given the user is authenticated, when the app loads, then the bottom navigation bar displays five tabs: Home, Contacts, Add, Work, and Notifications
- Given the bottom nav is visible, when the user taps a tab, then the corresponding screen is shown immediately without a full reload
- Given a tab is active, when the user views the bottom nav, then the active tab icon and label are visually distinct from inactive tabs using design token colors
- +2 more
As a As a user
I want I want the navigation shell to show only the tabs and routes that are relevant to my assigned role
So that So that I am not confused by sections that do not apply to me and cannot accidentally access restricted areas
- Given a peer mentor is authenticated, when the shell renders, then the Work tab content shows personal assignment inbox and activity summaries, not coordinator approval queues
- Given a coordinator is authenticated, when the shell renders, then the Work tab content includes member overview, activity approval queue, and proxy registration options
- Given an organization administrator is authenticated, when the shell renders, then the Home and Work tabs surface administrative dashboards and org configuration links
- +2 more
As a As a user
I want I want the navigation shell to automatically redirect me to the login screen if my session expires or I log out, and to restore my last active context after I re-authenticate
So that So that my session is always secure and I am never stranded on an authenticated screen without a valid session
- Given a user is authenticated and on any screen, when their Supabase session expires, then the navigation shell automatically redirects to the login screen and clears the authenticated navigation stack
- Given a user taps 'Log out', when the logout action completes, then the navigation stack is fully cleared and the login screen is shown with no back navigation possible to authenticated screens
- Given a user's session expired while they were away from the app, when they return and tap a push notification deep link, then they are shown the login screen first, and after authentication, they are taken to the deep link destination
- +2 more
As a As a user
I want I want to navigate between the five primary sections of the app — Home, Contacts, Add, Work, and Notifications — using the bottom navigation bar
So that So that I can quickly move between core app areas without losing my place or reloading content
- Given the user is authenticated, when the app loads, then the bottom navigation bar displays five tabs: Home, Contacts, Add, Work, and Notifications
- Given the bottom nav is visible, when the user taps a tab, then the corresponding screen is shown immediately without a full reload
- Given a tab is active, when the user views the bottom nav, then the active tab icon and label are visually distinct from inactive tabs using design token colors
- +2 more
As a As a user
I want I want the navigation shell to show only the tabs and routes that are relevant to my assigned role
So that So that I am not confused by sections that do not apply to me and cannot accidentally access restricted areas
- Given a peer mentor is authenticated, when the shell renders, then the Work tab content shows personal assignment inbox and activity summaries, not coordinator approval queues
- Given a coordinator is authenticated, when the shell renders, then the Work tab content includes member overview, activity approval queue, and proxy registration options
- Given an organization administrator is authenticated, when the shell renders, then the Home and Work tabs surface administrative dashboards and org configuration links
- +2 more
As a As a user
I want I want the navigation shell to automatically redirect me to the login screen if my session expires or I log out, and to restore my last active context after I re-authenticate
So that So that my session is always secure and I am never stranded on an authenticated screen without a valid session
- Given a user is authenticated and on any screen, when their Supabase session expires, then the navigation shell automatically redirects to the login screen and clears the authenticated navigation stack
- Given a user taps 'Log out', when the logout action completes, then the navigation stack is fully cleared and the login screen is shown with no back navigation possible to authenticated screens
- Given a user's session expired while they were away from the app, when they return and tap a push notification deep link, then they are shown the login screen first, and after authentication, they are taken to the deep link destination
- +2 more
As a As a user
I want I want to navigate between the five primary sections of the app — Home, Contacts, Add, Work, and Notifications — using the bottom navigation bar
So that So that I can quickly move between core app areas without losing my place or reloading content
- Given the user is authenticated, when the app loads, then the bottom navigation bar displays five tabs: Home, Contacts, Add, Work, and Notifications
- Given the bottom nav is visible, when the user taps a tab, then the corresponding screen is shown immediately without a full reload
- Given a tab is active, when the user views the bottom nav, then the active tab icon and label are visually distinct from inactive tabs using design token colors
- +2 more
As a As a user
I want I want the navigation shell to show only the tabs and routes that are relevant to my assigned role
So that So that I am not confused by sections that do not apply to me and cannot accidentally access restricted areas
- Given a peer mentor is authenticated, when the shell renders, then the Work tab content shows personal assignment inbox and activity summaries, not coordinator approval queues
- Given a coordinator is authenticated, when the shell renders, then the Work tab content includes member overview, activity approval queue, and proxy registration options
- Given an organization administrator is authenticated, when the shell renders, then the Home and Work tabs surface administrative dashboards and org configuration links
- +2 more