Understand the Codebase

Welcome to the technical heart of the MobileLauncher Standard. This boilerplate isn't just a collection of files; it's a production-ready system designed with a specific philosophy: "Offline-First, AI-Enhanced, and Feature-Driven."

This guide will help you understand how the project is structured, the technology powering it, and the security measures protecting it.

🚀 Features Overview

The boilerplate comes packed with features designed to cover 90% of SaaS app requirements out of the box.

👤 User & Core

• Authentication: Complete flow with Supabase Auth (email/password) and Social Login (Apple, Google).
• Onboarding: A highly configurable, multi-step onboarding wizard with A/B testing capabilities.
• User Profile: Profile management, avatar upload via Expo Image Picker, and settings.

🛠️ Productivity & Engagement

• Todo System: A full CRUD example showcasing the Offline-First architecture. It syncs automatically when functionality is restored.
• Gamification: Built-in streaks, badges, and points system to keep users engaged.
• Journaling: A template for daily data entry apps (morning/evening logs).

💰 Monetization

• Paywall: Integrated with RevenueCat for subscriptions and one-time purchases. Includes a high-conversion UI.
• Offerings: Dynamic fetching of subscription tiers.

⚙️ System Features

• Notifications: Push notifications (FCM) and local scheduled reminders.
• Remote Config: Update feature flags and constants without App Store releases using Firebase Remote Config.
• OTA Updates: Push JavaScript fixes instantly with Expo Updates.

🏗️ Architecture: Feature-First

We strictly follow a Feature-First Architecture. Instead of grouping files by type (e.g., all components in one folder, all screens in another), we group them by business domain.

Why?

• Scalability: Adding a new feature doesn't require touching 10 different folders.
• Maintainability: You can delete a feature by deleting one folder.
• AI Compatibility: Agents understand the context of a "Feature" better when all related files are co-located.

Directory Structure

src/ is the core of your application:

1. features/ (The Core)
   • Contains 80% of your code. Each subfolder is a self-contained feature (e.g., auth, todos, payment).
   • Anatomy of a Feature:
     • api/: RTK Query endpoints.
     • components/: UI components specific to this feature.
     • screens/: Full screens registered in navigation.
     • store/: Redux slice and selectors.
     • index.ts: The public API of the feature.

3. Navigation Structure (src/navigation/)

We use a hybrid navigation stack:

• RootNavigator: The parent stack. Handles global modals and the switch between Auth/Main flows.
• TabNavigator: The main dashboard (Home, Search, Profile).
• AuthNavigator: Login, Sign Up, Forgot Password screens.

This separation ensures that authenticated users can't accidentally navigate back to the login screen.

4. State Management (Redux Toolkit)

The store is configured in src/store/store.ts. It combines:

• Slices: auth, todos, onboarding (standard Redux state).
• RTK Query: api (caching & data fetching).
• Persistence: redux-persist with MMKV (saves state to disk).

// src/store/store.ts (Simplified)
export const store = configureStore({
  reducer: persistedReducer,
  middleware: (getDefault) => getDefault().concat(api.middleware),
});

We primarily use RTK Query for data to avoid manually managing loading/error states.

🎨 Design System (src/ui/)

We use Shopify Restyle for a type-safe theme. The theme is defined in src/ui/style/theme.ts.

Theme Structure

You can easily customize the look of your app by editing the colors or spacing objects.

// src/ui/style/theme.ts
const theme = createTheme({
  colors: {
    mainBackground: palette.white,
    mainForeground: palette.black,
    primaryCardBackground: palette.purplePrimary,
    // ...
  },
  spacing: {
    s: 8,
    m: 16,
    l: 24,
    xl: 40,
  },
  textVariants: {
    header: {
      fontSize: 34,
      fontWeight: 'bold',
      color: 'mainForeground',
    },
    body: {
      fontSize: 16,
      lineHeight: 24,
      color: 'bodyText',
    },
  },
});

3. services/ (The Infrastructure)

   • Wrappers for 3rd party libraries.
   • api/: Base API configuration.
   • storage/: MMKV and SecureStore wrappers.
   • logger/: Unified logging system (console + Sentry/Crashlytics).

4. store/ (Global State)

   • Configures the Redux store and persistence.

Visualizing the Architecture

graph TD
    A[App Entry Point] --> B[Navigation Layer]
    B --> C[Feature: Auth]
    B --> D[Feature: Todos]
    B --> E[Feature: Settings]
    
    subgraph "Feature: Todos"
        D1[Screens] --> D2[Components]
        D2 --> D3[Hooks]
        D3 --> D4[RTK Query API]
        D3 --> D5[Redux Slice]
    end
    
    D4 --> F[Global Services]
    F --> G[Supabase/API]

🛠️ Technology Stack

We use the latest, most stable tools in the React Native ecosystem.

Code Comparison: Styles

Why we use Restyle instead of standard StyleSheet.

const styles = StyleSheet.create({
  container: {
    padding: 16,
    marginTop: 20,
    backgroundColor: 'white'
  }
});

<Box 
  padding="m" 
  marginTop="xl" 
  bg="mainBackground"
>
  <Text variant="header">Hello</Text>
</Box>

🔒 Security

Security is baked into the foundation, not added as an afterthought.

1. Authentication & Session

• Providers: We use Supabase (or Firebase) for identity management.
• Tokens: Session tokens (JWTs) are never stored in AsyncStorage. We use expo-secure-store to encrypt sensitive data on the device.

2. Data Access Control

• Row Level Security (RLS): If using Supabase, data security is enforced at the database level. Users can only access their own rows. The client cannot bypass this.

3. API Security

• Encryption: All traffic is essentially SSL/TLS encrypted.
• Secrets: Environment variables (EXPO_PUBLIC_...) are used for public keys only. Service accounts are never included in the app bundle.

⚡ Performance

The Classic mistake in optimization is "guessing." We optimized the core architecture so you don't have to guess.

1. List Rendering

We use FlashList (by Shopify) instead of FlatList.

• Why?: It recycles components more efficiently, running 5x-10x faster on the JS thread.
• Result: Smooth scrolling even with thousands of items.

Performance Benchmark:

// ❌ FlatList (Laggy on large lists)
<FlatList
  data={data}
  renderItem={renderItem}
/>

// ✅ FlashList (60fps)
<FlashList
  data={data}
  renderItem={renderItem}
  estimatedItemSize={50} // Critical for performance
/>

2. Image Optimization

• We use expo-image for aggressive caching and optimized decoding.
• Images fade in largely to improve perceived performance.

3. State Persistence

• We use MMKV instead of AsyncStorage.
• Benefit: MMKV is synchronous and roughly 30x faster. This means the app loads state instantly on boot, with no "loading..." flash.

4. Bundle Size

• The code is tree-shaken.
• Heavy libraries (like Moment.js) are banned in favor of lightweight alternatives (like date-fns or raw Intl).