Organization Route Guard
Component Detail
Description
go_router redirect guard that intercepts navigation for unauthenticated users or users without an active organization context and redirects them to the Organization Selection Screen. Evaluates both the authentication state and the presence of a valid tenant context on every navigation event to ensure no screen is reached without proper context seeding.
org-route-guard
Summaries
The Organization Route Guard acts as a security checkpoint that ensures every user navigating through the mobile application is properly authenticated and operating within a valid organizational context before accessing any protected screen. By intercepting all navigation events and enforcing both identity and tenant membership checks, this component directly reduces the risk of unauthorized data exposure across partner organizations — a critical concern in multi-tenant B2B environments. It protects the business from compliance failures, data leakage between tenants, and reputational damage caused by unauthorized access, while simultaneously ensuring that paying partner organizations can trust that their data is siloed appropriately. This capability is foundational to winning and retaining enterprise contracts where security and data segregation are non-negotiable requirements.
The Organization Route Guard is a medium-complexity mobile infrastructure component that must be implemented early in the project timeline, as it gates access to virtually every feature in the app. Its primary dependency on the tenant-context-service means that service must be stable and fully tested before route guard integration testing can begin — schedule accordingly to avoid blocking downstream feature work. Testing requirements include coverage for unauthenticated users, authenticated users with no org context, users with a valid org context, and edge cases like session expiry mid-navigation. Because this component intercepts all navigation events, any regression here has the potential to break the entire app flow, so thorough automated integration tests and staged rollout are strongly recommended.
Plan for at least one dedicated QA cycle focused solely on navigation flows after any change to auth or tenant context logic.
The Organization Route Guard implements the go_router `redirect` callback pattern, evaluating two conditions on every navigation event: `isAuthenticated()` and `isOrgContextValid()`. It integrates with `tenant-context-service` to read the current tenant state synchronously during the redirect evaluation — this means the tenant context service must expose a synchronous (non-async) getter for the guard to function correctly within go_router's redirect lifecycle, which is called synchronously. The `redirect` method returns a nullable String: returning null allows navigation to proceed, while returning a path string (e.g., `/org-select`) triggers a redirect. Because this is a shared component used across all features, changes to its logic require re-testing all protected routes.
Be cautious of race conditions during app startup where auth and org context may not yet be hydrated — guard must handle null/loading states gracefully without causing redirect loops.
Responsibilities
- Intercept all go_router navigation events
- Check authentication state before routing
- Check presence of valid org context before routing
- Redirect to organization selection screen when context is missing
- Allow navigation to proceed when both auth and org context are valid
Interfaces
redirect(BuildContext context, GoRouterState state) -> String?
isOrgContextValid() -> bool
isAuthenticated() -> bool
Relationships
Related Data Entities (2)
Data entities managed by this component