App State & Providers
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The App State & Providers system in LiveCanvas Mobile establishes the foundational execution environment for the React Native application. It manages critical concerns such as environment resolution, theme injection, and the "Startup Gate" which ensures the runtime is fully hydrated before the main UI tree is mounted. This architecture centralizes global concerns at the top of the component tree to provide consistent data access through React Context.
The system acts as a bridge between the underlying configuration (environment variables and theme tokens) and the functional components. By wrapping the application in a series of specialized providers, the project ensures that state—ranging from visual styles to authentication session snapshots—is consistently available and reactive across all screens and modules.
Sources: mobile/src/providers/AppProviders.tsx:10-21, mobile/src/providers/StartupGate.tsx:32-41
Global Provider Architecture
The AppProviders component serves as the root container for all global React Context providers. It initializes the application environment and stacks providers in a specific order to ensure dependency resolution.
The diagram above illustrates the provider hierarchy. ThemeProvider is placed above the StartupGate to ensure that even the startup screens can access the design system's color and spacing tokens.
Sources: mobile/src/providers/AppProviders.tsx:12-23
Key Providers
| Provider | Purpose | Dependencies |
|---|---|---|
SafeAreaProvider | Handles notch and system UI insets. | None |
ThemeProvider | Injects the design system (colors, spacing, radius). | colors, tokens |
StartupGate | Manages runtime hydration and forced logout routing. | environment |
Sources: mobile/src/providers/AppProviders.tsx:14-20, mobile/src/providers/ThemeProvider.tsx:44-50, mobile/src/providers/StartupGate.tsx:28-31
Runtime Hydration & Startup Gate
The StartupGate is a critical state management component that prevents the application from rendering its main content until the runtime environment is fully prepared. It handles the transition from a "booting" state to a "ready" state by executing the bootstrapRuntime function.
Startup States
The runtime exists in one of two primary states defined by the StartupState type:
- booting: The initial state where the app displays a placeholder screen while hydrating local session data.
- ready: The state achieved once a
StartupSnapshotis available, allowing the application to render its children.
Sources: mobile/src/providers/StartupGate.tsx:18-24
Forced Logout Logic
If the bootSessionState in the StartupSnapshot indicates a forced_logout, the StartupGate performs a transition to the sign-in route. It uses a temporary overlay screen while the expo-router performs the navigation.
The sequence diagram shows the boot flow and the conditional routing logic applied during initialization.
Sources: mobile/src/providers/StartupGate.tsx:41-86
Theme & Design System State
The ThemeProvider manages the visual state of the application. It provides an AppTheme object via context, which components consume using the useAppTheme hook. This object contains structured tokens for colors, spacing, and border radii.
Theme Data Structure
The theme is composed of the following token groups:
- Colors: Includes semantic keys like
background,surface,accent, anderror. - Spacing: A scale (xs to xl) in logical pixels for consistent layouts.
- Radius: Presets for border rounding, including
sm,md,lg, andpill.
Sources: mobile/src/providers/ThemeProvider.tsx:10-41, mobile/src/theme/tokens.ts:4-22
Usage in Components
Components utilize the theme to apply dynamic styling that adheres to the central design system.
export function AppCard({ children, style }: AppCardProps) {
const theme = useAppTheme();
return (
<View
style={[
styles.card,
{
backgroundColor: theme.colors.surface,
borderColor: theme.colors.border,
},
style,
]}
>
{children}
</View>
);
}
Sources: mobile/src/components/AppCard.tsx:14-30
Durable vs Ephemeral State
The overall architecture distinguishes between state that must persist in the backend and state maintained in the frontend runtime.
| State Category | Storage Location | Examples |
|---|---|---|
| Durable | PostgreSQL (Backend) | User accounts, Follows, Posts, Chat history. |
| Ephemeral | OTP / Presence / PubSub | Active presence, Countdown status, Typing indicators. |
| Local Shell | React Context / Local Storage | Session snapshots, Theme selection, Env config. |
Sources: ARCHITECTURE.md:144-162, mobile/src/providers/StartupGate.tsx:90-94
GraphQL Integration
The application's durable state is synchronized via GraphQL queries and mutations. The schema defines types like User, Post, and LiveSession which are reflected in the client-side state after fetching.
Sources: mobile/schema.graphql:328-360
Conclusion
The App State & Providers module provides the necessary infrastructure to manage the application's lifecycle and global configurations. By utilizing a gated startup process and a strongly typed theme provider, LiveCanvas ensures that the mobile client remains stable, visually consistent, and correctly synchronized with the backend environment from the moment of launch.