Resume Session in Correct Organizational Context After App Restart
Returning users should not be required to re-select their organization every session. The tenant-session-store (674-tenant-session-store) persists the selected organization identifier securely using the secure-storage-adapter (676-secure-storage-adapter / 030-secure-storage-adapter). On app launch, after authentication (biometric or credential-based), the org-route-guard (671-org-route-guard) checks for a persisted org context and, if valid and the user's membership is still active, bypasses the org selection screen and navigates directly to the role-based home screen. If the persisted organization is no longer valid (membership revoked, org disabled), the guard redirects to the org selection screen with an appropriate explanation.
User Story
Audience Summaries
For high-frequency users such as the peer mentor documented with 380 individual activity registrations in a single year, requiring organization re-selection on every app launch would accumulate into meaningful daily friction, increasing cognitive load and reducing registration completeness. This story delivers session resumption in the correct organizational context, eliminating a repetitive step that contradicts the platform's core design goal of minimizing clicks per registration session. Beyond usability, the story enforces secure storage of the org identifier — preventing plaintext exposure of organizational membership data on the device. Seamless resumption with correct context is a baseline expectation for any professional-grade mobile tool and directly supports volunteer retention and data completeness goals.
This story depends on story-organization-selection-screen-peer-mentor-001 and involves coordination between the authentication layer, secure storage adapter (676/030-secure-storage-adapter), tenant session store (674-tenant-session-store), and org route guard (671-org-route-guard). Delivery complexity is moderate-to-high: the guard must handle four distinct scenarios — valid persisted context, revoked membership, offline launch with stale cache, and updated context from in-session switching. Acceptance criteria cover all four cases plus a security verification requirement (secure storage, not plaintext). QA must validate biometric auth integration, offline behavior with cached org data, and the revoked-membership redirect with user-facing messaging.
Security review of the storage adapter is recommended before release to confirm org identifiers are stored in the secure partition across both iOS and Android.
On app launch post-authentication, the 671-org-route-guard reads the persisted org identifier from 676-secure-storage-adapter (platform secure storage, not shared preferences). It validates the identifier against current membership status — querying locally cached data when offline. If valid, the guard bypasses the org selection screen and navigates to the role-based home screen. If the membership has been revoked or the org disabled, it redirects to the org selection screen with an explanatory message.
The 674-tenant-session-store must be updated whenever the in-session switcher changes the active org, so the persisted value always reflects the most recently selected organization. Key technical concerns: secure storage read/write on both platforms, handling async guard resolution before navigation, offline fallback with stale-data banner, and ensuring the guard fires after biometric authentication resolves. Integration tests should cover all five acceptance criteria scenarios with mocked storage and membership states.
Acceptance Criteria
- Given I previously selected an organization and closed the app, When I reopen the app and authenticate with biometrics, Then I am taken directly to the home screen of my previously selected organization without seeing the org selection screen
- Given I have a persisted organization selection, When the app launches and my membership in that organization has been revoked, Then I am redirected to the org selection screen with a message explaining that my access to the previous organization has changed
- Given I have a persisted organization selection, When the app launches offline, Then the app uses the locally cached org context to load available offline data, displaying a banner indicating that data may be stale
- Given I have selected a new organization via the in-session switcher, When I close and reopen the app, Then the app resumes in the most recently selected organization
- Given the persisted org context is stored, When I examine app storage on the device, Then the organization identifier is stored in the secure storage partition and not in plaintext shared preferences
Business Value
HLF reported a peer mentor with 380 individual activity registrations in a single year. For high-frequency users like this, requiring organization re-selection on every app open would create significant daily friction that accumulates into meaningful time waste and frustration. Session resumption with the correct organizational context is a baseline usability requirement that directly supports the workshop's stated goal of keeping cognitive load and number of clicks as low as possible for every registration session. It also ensures data security by storing the org identifier in secure storage rather than plaintext.
Components
- Organization Persistence Repository data
- Local Storage Adapter infrastructure
- Secure Storage Adapter infrastructure
- Session Resume Manager service
- Secure Session Storage data
- Organization Route Guard service
- Organization Repository data
- Tenant Session Store data
- Organization Branding Cache data
- Secure Storage Adapter infrastructure