Mobile architecture

app/
├── (tabs)/                   # Tab navigation group
│   ├── _layout.tsx          # Tab bar config (custom AnimatedTabBar, initialRoute "events")
│   ├── events/              # "Gigs" tab — index, create, sample, [id]/, templates/
│   ├── mailbox/             # "Mailbox" tab — invitations, crew offers, availability checks
│   ├── browse/              # "Browse" tab — hub of secondary surfaces (see below)
│   └── you/                 # "You" tab — profile, settings (incl. availability hours), org-settings
├── _layout.tsx              # Root layout (providers)
├── index.tsx                # Entry point / redirect
├── login.tsx  signup.tsx    # Auth + founder / org-invite wizards
├── forgot-password.tsx  set-password.tsx
├── oauth-callback.tsx  sso-needs-password.tsx  sso-pending-task.tsx
├── onboarding/  ensure-org/  # Redirects to /signup
├── chat/  profile/
├── privacy-policy.tsx  terms-of-service.tsx
└── +not-found.tsx

// app/_layout.tsx (RootLayout, wrapped in Sentry.wrap when a DSN is set)
<ThemeProvider>
  <ErrorBoundary>
    <ClerkProvider>
      <AppProviders>          {/* lib/providers/AppProviders.tsx */}
        <Stack />             {/* expo-router */}
      </AppProviders>
    </ClerkProvider>
  </ErrorBoundary>
</ThemeProvider>

// AppProviders (inner stack)
<QueryProvider>                 {/* TanStack Query — lib/query/QueryProvider.tsx */}
  <NetworkProvider>
    <AuthProvider>
      <PostHogProvider>
        {/* AuthSessionTelemetryBridge + ScreenTracker (siblings) */}
        <ChatProvider>
          {children}

import { useAuth } from '@/lib/context/AuthContext';

function MyComponent() {
  const { user, isSignedIn, signOut } = useAuth();

  if (!isSignedIn) {
    return <LoginPrompt />;
  }

  return <UserProfile user={user} />;
}

import { View } from 'react-native';
import { Text } from '@/components/ui/text';

<View className="bg-background p-4">
  <Text className="text-foreground font-semibold">Hello</Text>
</View>

components/
├── ui/                     # shadcn-for-RN (@rn-primitives + NativeWind)
│   ├── button.tsx  text.tsx  tabs.tsx  select.tsx  bottom-sheet-modal.tsx  ...
│   └── ...                 # cva variants, className-driven
├── AnimatedTabBar.tsx      # Custom tab bar
├── events/  shared/        # Feature / shared components
└── ErrorBoundary.tsx

// A query hook wrapping a service call
const { data: events, isLoading } = useQuery({
  queryKey: ['events', orgId],
  queryFn: () => eventService.getByOrg(orgId),
});

┌─────────────────┐
│   User Login    │
│  (via Clerk)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Clerk Session   │
│   Established   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  AuthContext    │
│  sets up token  │
│  getter         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  API Request    │
│  (with Bearer)  │
└─────────────────┘

import { useTabFocus } from '@/lib/hooks/useTabFocus';

function EventsScreen() {
  const { refreshData } = useTabFocus({
    onFocus: async () => {
      // Refresh data when tab becomes active
      await fetchEvents();
    },
    cacheDuration: 5 * 60 * 1000, // 5 minutes
  });

  return (
    <FlatList
      data={events}
      onRefresh={refreshData}
      refreshing={isRefreshing}
      // ...
    />
  );
}

// In tab navigator configuration
<Tabs
  screenOptions={{
    lazy: false, // Preload all tabs
  }}
/>

// Memoize expensive components
const EventCard = memo(function EventCard({ event }) {
  return (
    <Box>
      <Text>{event.title}</Text>
    </Box>
  );
});

// components/ErrorBoundary.tsx
<ErrorBoundary
  fallback={<ErrorScreen />}
  onError={(error, info) => {
    // Report to Sentry
    reportError(error, info);
  }}
>
  <App />
</ErrorBoundary>

try {
  const data = await httpClient.get('/api/v1/events');
  setEvents(data);
} catch (error) {
  if (error.status === 401) {
    // Handle unauthorized
    signOut();
  } else {
    // Show user-friendly error
    showError('Failed to load events');
  }
}