Navigation & Routing System
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Navigation & Routing System in LiveCanvas is built using Expo Router, providing a file-based routing architecture for the mobile application. It manages the transition between different application states, including unauthenticated entry points, the authenticated core "shell," and specialized modal overlays. The system is designed to handle deep linking, session-based redirection, and initial application hydration through a centralized startup gate.
This system ensures that users are directed to the appropriate interface based on their authentication status (e.g., signed_in vs forced_logout) while maintaining a consistent navigation state across the app's modular structure.
Sources: mobile/package.json:13, mobile/src/config/runtime.ts:8-13, mobile/src/providers/StartupGate.tsx:68-75
Routing Architecture
The application organizes routes into logical groups using directory-based nesting. This separation allows the system to apply different layouts and access rules to specific sections of the app.
Route Groups
The following table describes the primary route groups identified in the project:
| Group | Path Prefix | Purpose |
|---|---|---|
| Auth | /(auth) | Entry point for unauthenticated flows like Sign In. |
| App | /(app) | The durable authenticated experience (e.g., Home, Profile). |
| Modals | /(modals) | Specialized entry points for transient states like Live Sessions. |
Sources: mobile/app/(auth)/sign-in.tsx, mobile/app/(app)/home.tsx, mobile/app/(modals)/live-session.tsx
Navigation Flow
The following diagram illustrates how the application determines the initial route during the bootstrap process:
Startup & Hydration Logic
The system utilizes a StartupGate component to manage the transition from a "booting" state to a "ready" state. During this phase, the application hydrates the local session and determines if a reset is required.
Runtime Bootstrapping
The bootstrapRuntime function handles initial URL retrieval and derives a StartupSnapshot. This snapshot dictates the landingHref based on the environment's bootSessionState.
- Initial Href Extraction: The system parses deep links to find matching routes within a known set of valid HREFs (
/sign-in,/home,/profile,/live-session). - Forced Logout Handling: If the session state indicates a forced logout, the system overrides any deep links to ensure the user is redirected to the sign-in screen.
Sources: mobile/src/config/runtime.ts:16-38, mobile/src/config/runtime.ts:85-103
Startup State Transitions
The StartupGate tracks the progression of the application lifecycle:
- Booting: Displays a
StartupScreenwith an activity indicator while session hydration occurs. - Ready: Provides the
StartupContextto the children components and allows navigation to proceed. - Transitioning: If a
forced_logoutoccurs, a specialized overlay is shown while the navigator replaces the current route with/sign-in.
Components & Utilities
Key Navigation Hooks
useRouter(): Utilized within screens to perform manual navigation (e.g.,router.push('/profile')orrouter.replace('/sign-in')).useStartupState(): Accesses the current environment and startup snapshot within the component tree.
Sources: mobile/app/(app)/home.tsx:11-28, mobile/src/providers/StartupGate.tsx:174-182
Configuration Data Structures
The StartupSnapshot represents the result of the routing decision logic:
export type StartupSnapshot = {
initialUrl: string | null; // The raw URL that opened the app
initialHref: string | null; // The parsed internal route
landingHref: string; // The final calculated destination
defaultHref: string; // Fallback if no initialHref exists
bootSessionState: BootSessionState;
resetReason: 'forced_logout' | null;
};
Sources: mobile/src/config/runtime.ts:16-23
Summary
The Navigation & Routing System provides a robust foundation for the LiveCanvas mobile app by combining Expo Router's file-based conventions with a custom startup lifecycle. By centralizing route derivation and session-based redirection in runtime.ts and StartupGate.tsx, the system ensures secure and predictable navigation from the moment the app is launched or deep-linked.