Sign In with Email and Password
Peer mentors need a reliable, straightforward email and password login flow as the foundational authentication method. The login screen must present a clean form with email and password fields, real-time inline validation, and a clear submit action. The form should be keyboard-aware so the input fields are never obscured by the software keyboard, particularly important on smaller devices. Upon successful authentication, the user is routed to their role-specific home screen. Failed authentication must surface a clear, plain-language error without exposing security details.
User Story
Audience Summaries
Email and password authentication is the foundational entry point to the entire platform — without it, no peer mentor can access activity registration, contact management, or reporting. This story is rated critical because it unblocks the full value chain of the product. A frictionless, error-tolerant login experience directly reduces abandonment at the highest-friction point in the user journey, improving activation rates and reducing the cost of onboarding support. Plain-language error messaging without exposing security internals builds trust with less technically experienced users, a key segment of the peer mentor population.
Persistent session storage eliminates repeated logins, increasing daily engagement frequency and reinforcing habit formation among the mentor cohort.
As a critical-priority story with no upstream dependencies, this should be scheduled in the earliest development sprint. It is itself a dependency for all authenticated flows in the app. Delivery involves coordination between the mobile frontend team (form UI, validation, keyboard handling), the backend/auth team (Supabase Auth configuration, token management), and QA (credential validation scenarios, error state coverage, session persistence tests). The 3-second authentication SLA in the acceptance criteria requires load testing against the Supabase Auth endpoint under realistic network conditions.
Rollout planning should include a smoke test checklist covering all six acceptance criteria before any feature work that depends on an authenticated session is merged. Risk: Supabase Auth configuration delays could block the entire feature pipeline.
This story requires building the login screen UI with email and password `TextInput` fields, inline validation logic (email format check client-side before any network call), and a submit handler wired to Supabase Auth's `signInWithPassword` API. On success, the auth token must be persisted via secure storage (e.g., `expo-secure-store` or equivalent) and the navigation stack reset to the peer mentor home screen. On failure, error responses from Supabase must be mapped to plain-language messages — avoid exposing which field is incorrect for security reasons. The form must integrate the keyboard-aware layout wrapper established in story 432.
Session restoration on app launch requires checking for a valid stored token before rendering the login screen. Consider abstracting auth state into a context provider or Zustand/Redux slice for consumption across the app. Unit tests should cover validation logic; integration tests should mock Supabase Auth responses for success, invalid credentials, and network failure scenarios.
Acceptance Criteria
- Given the app is launched and no session exists, When the user navigates past org selection, Then the login screen is displayed with email and password fields and a sign-in button
- Given the login screen is visible, When the user taps the password field, Then the keyboard appears and the form scrolls so the password field remains visible above the keyboard
- Given valid credentials are entered, When the user taps sign in, Then the app authenticates via Supabase Auth and navigates to the peer mentor home screen within 3 seconds
- Given invalid credentials are entered, When the user taps sign in, Then a clear error message is shown (e.g. 'Incorrect email or password') without revealing which field is wrong
- Given the email field is empty or malformed, When the user taps sign in, Then inline validation highlights the email field with a descriptive error before any network request is made
- Given a successful login, When the session is established, Then the auth token is securely stored so subsequent app launches skip the login screen
Business Value
Email and password login is the baseline authentication method that enables every peer mentor to access the platform. Without this, no other feature is reachable. It directly unblocks activity registration, reporting, and contact management — the core value of the app. A frictionless login experience reduces dropout at the entry point and sets the tone for the overall quality of the product.
Components
- Login Screen ui
- Login Form ui
- Login Form BLoC service
- Credential Validator service
- Authentication Service service
- Authentication Repository data
- Supabase Auth Client infrastructure
- Keyboard-Aware Layout Utility infrastructure
- Authentication Session Manager service
- Auth Token Store data
- Secure Storage Adapter infrastructure