Switch Organization During an Active Session
Peer mentors who are members of multiple organizations need to switch between them without going through the full authentication flow again. The multi-org context switcher (667-multi-org-context-switcher) provides an in-session mechanism — accessible from the settings or profile menu — that re-presents the organization selection screen. On selection, the tenant context is updated, RLS policies are reconfigured for Supabase, and the app navigates back to the home screen in the new organizational context. All cached data from the previous org session is cleared to prevent cross-org data bleed.
User Story
Audience Summaries
This high-priority story directly addresses a core NHF requirement: peer mentors belonging to up to 5 local chapters must be able to switch organizational context without logging out and back in. Without seamless in-session org switching, multi-chapter volunteers face friction severe enough to drive abandonment and underreporting of activities. Accurate multi-chapter activity attribution is a prerequisite for Bufdir compliance reporting, meaning this feature has direct regulatory and funding implications. Retaining high-frequency volunteers and ensuring complete activity data protects the organization's reporting integrity, stakeholder trust, and continued program funding.
This is not a convenience feature — it is a foundational capability that determines whether the platform is viable for its primary user segment.
This story has high delivery priority and moderate-to-high complexity due to the multi-layered context switching requirements. Key deliverables include the org switcher UI component (667-multi-org-context-switcher), Supabase RLS reconfiguration logic on org switch, and cache invalidation for all org-scoped data (contacts, activities, labels). Cross-functional dependencies include the authentication flow, database access layer, and navigation system. Acceptance criteria are well-defined and testable, with five scenarios covering normal switching, data isolation, RLS update, cache clearing, and single-org edge cases.
QA must validate data isolation rigorously — cross-org data bleed is a critical failure mode. Rollout should include regression testing on all org-scoped data queries to confirm RLS policies apply correctly after context change.
Implementation centers on the 667-multi-org-context-switcher component, accessible from the settings or profile menu. On org selection, three sequential operations must complete atomically: (1) update the tenant context store with the new org identifier, (2) reconfigure Supabase RLS policies to scope all subsequent queries to the new org, and (3) invalidate all cached data tied to the previous org context — including contact lists, activity types, and org labels. The app then navigates to the home screen in the new context. Edge cases include handling mid-switch failures (partial RLS update), ensuring no previous org data leaks into the new session, and correctly indicating the active org in the switcher UI.
Dependencies include the tenant context store, cache management layer, Supabase client configuration, and the org-aware navigation router. Tests must cover RLS enforcement, cache invalidation completeness, and UI state accuracy.
Acceptance Criteria
- Given I am in an active session with Organization A, When I access the organization switcher in settings, Then I see a list of all my organizations with the currently active one indicated
- Given I select a different organization from the switcher, When the switch completes, Then I am taken to the home screen for the new organization and all visible data (contacts, activities, stats) reflects that organization only
- Given I switch organizations, When the new tenant context is set, Then the Supabase RLS configuration is updated to scope all queries to the new organization's data
- Given I switch organizations, When the context changes, Then any cached data (contact lists, activity types, org labels) from the previous organization is invalidated and reloaded for the new organization
- Given I am the only member of my current organization, When I open the org switcher, Then I see only my one organization and a clear indication that no other organizations are available to switch to
Business Value
NHF explicitly identified members belonging to up to 5 local chapters as a core requirement. Without in-session org switching, a peer mentor active in multiple chapters would need to log out and back in every time they shift context — creating friction severe enough to drive abandonment and underreporting. Seamless switching is a prerequisite for accurate multi-chapter activity attribution, which directly affects the quality of Bufdir compliance reporting.
Components
- Multi-Organization Context Switcher ui
- Tenant Context Service service
- Organization Selection Service service
- Organization Route Guard service
- Multi-Organization Membership Resolver service
- Organization Repository data
- Tenant Session Store data
- Organization Branding Cache data
- Supabase RLS Tenant Scope Configurator infrastructure
- Feature Flag Provider infrastructure