Remain authenticated across app restarts
After a successful email/password login, the Supabase JWT session token is securely persisted via Flutter Secure Storage. When the app restarts, the Auth Repository checks for a valid existing session and silently refreshes the token if needed using Supabase's built-in refresh mechanism. If a valid session exists, the user is navigated directly to their role-specific home screen, bypassing the login screen entirely. If the session has expired beyond the refresh window, the user is navigated to the login screen with an optional informational message. This behavior is essential for peer mentors who open the app briefly multiple times per day in the field.
User Story
Acceptance Criteria
- Given a user has successfully logged in, when they close and reopen the app within the session validity window, then they are navigated directly to the home screen without seeing the login screen
- Given the app starts with a stored session that is close to expiry, when the Auth Repository detects a refresh is needed, then the token is silently refreshed without interrupting the user
- Given a session has fully expired, when the app restarts, then the user is navigated to the login screen
- Given the user logs out explicitly, when the app is reopened, then no session data is present and the login screen is shown
- Given secure storage, when the session token is persisted, then it is stored using Flutter Secure Storage and is not accessible via standard file system access
Business Value
Session persistence is a baseline usability requirement for a mobile app used in the field. Peer mentors open the app immediately after peer support visits to log activities — requiring re-login each time would create friction that leads to underreporting, which is the core problem the app is solving. For coordinators who use the app throughout the working day, repeated logins are a significant productivity drain. Session persistence with secure token storage also sets the security foundation required for handling sensitive personal data about vulnerable individuals.
Components
- Auth Service service
- Auth Repository data
- Supabase Auth infrastructure