React Native
Frontend System Design

The Core Idea

Large RN apps should follow a feature-based (vertical slice) architecture, not a layer-based one. Group by feature, not by type. Each feature is self-contained — it owns its components, hooks, store slices, types, and tests.

Recommended Structure

src/
├── app/               # App entry, providers, global setup
│   ├── App.tsx
│   ├── providers/     # Redux, Theme, Navigation providers
│   └── store/         # Root store configuration
│
├── features/          # ✅ Feature-based vertical slices
│   ├── auth/
│   │   ├── components/
│   │   ├── screens/
│   │   ├── hooks/
│   │   ├── store/     # authSlice.ts
│   │   ├── api/       # authApi.ts (RTK Query / axios)
│   │   ├── types/
│   │   └── index.ts   # Public API of the feature
│   ├── feed/
│   ├── profile/
│   └── chat/
│
├── shared/            # Truly shared, no feature dependency
│   ├── components/    # Button, Modal, Avatar…
│   ├── hooks/         # useDebounce, useTheme…
│   ├── utils/         # formatDate, validators…
│   ├── constants/
│   └── theme/
│
├── navigation/        # All navigation config
│   ├── RootNavigator.tsx
│   ├── AuthNavigator.tsx
│   └── MainTabNavigator.tsx
│
└── services/          # External: analytics, storage, push
    ├── analytics.ts
    ├── storage.ts
    └── notifications.ts

Key Principles

• Feature boundaries: Features can import from shared/ but never from each other directly — use events or the root store.
• Barrel exports: Each feature has an index.ts that defines its public API. Other code only imports from that barrel.
• Co-location: Keep tests, types, and styles next to the code they describe.
• Absolute imports: Configure tsconfig.json path aliases like @features/auth to avoid ../../../ hell.

Old Architecture (The Bridge)

New Architecture (JSI + Fabric + TurboModules)

Practical Improvements

Choose React Native when:

• Your team is JS/React-heavy and you want to share logic with a web app
• You need platform-native UI components (accessibility, OS updates for free)
• You're integrating a large existing native codebase incrementally
• Time-to-market is critical and you have one team

Choose Native when:

• Maximum graphics performance (games, AR, complex camera processing)
• Heavy use of cutting-edge platform APIs before they have RN wrappers
• Apps where platform-specific UX is a competitive differentiator (e.g. banking)

State Classification First

Before picking a library, classify your state into 4 categories:

Recommended Stack

// 1. Server state — React Query handles caching, refetch, pagination
const { data: feed, isLoading } = useQuery({
  queryKey: ['feed', userId],
  queryFn: () => fetchFeed(userId),
  staleTime: 60_000,        // 1 minute fresh
  cacheTime: 5 * 60_000,    // 5 minutes in cache
});

// 2. Global UI state — Zustand (lightweight, no boilerplate)
const useAuthStore = create((set) => ({
  user: null,
  token: null,
  login: (user, token) => set({ user, token }),
  logout: () => set({ user: null, token: null }),
}));

// 3. Local state — just useState, no global store needed
const [isLiked, setIsLiked] = useState(false);

Key Design Decisions

• Don't put server data in Redux — it creates a second cache that conflicts with your API cache. Use React Query for all server-sourced data.
• Optimistic updates: For likes/follows, update local state immediately, then revert on API failure for instant UX.
• Normalized cache: If using Redux, use createEntityAdapter to normalize data — a post should live in one place even if referenced from feed, profile, and search.
• Persistence: Use redux-persist or Zustand's persist middleware for auth tokens and offline support.

Context API Performance Problem

// ❌ Bad: ALL consumers re-render when ANY value changes
const AppContext = createContext();
function AppProvider({ children }) {
  const [user, setUser] = useState(null);
  const [theme, setTheme] = useState('dark');
  const [cart, setCart] = useState([]);
  // Every Cart update re-renders ALL context consumers
  return <AppContext.Provider value={{ user, theme, cart }}>
    {children}
  </AppContext.Provider>;
}

// ✅ Good: Split contexts or use Zustand selectors
const useCartStore = create((set) => ({ cart: [] }));
const CartBadge = () => {
  // Only re-renders when cart.length changes
  const count = useCartStore(state => state.cart.length);
  return <Text>{count}</Text>;
};

Diagnosis First

Before optimizing, profile with Flipper's React DevTools or the RN Performance Monitor to identify what is slow — JS thread, UI thread, or renders.

Solution: Layered Optimization Approach

// ✅ Optimized FlatList pattern
const PostItem = React.memo(({ item, onLike }) => (
  <View>
    <Text>{item.title}</Text>
    <TouchableOpacity onPress={() => onLike(item.id)}>
      <Text>Like</Text>
    </TouchableOpacity>
  </View>
));

function Feed() {
  const handleLike = useCallback((id) => {
    // stable reference, won't cause re-renders
    likePost(id);
  }, []);

  const renderItem = useCallback(({ item }) => (
    <PostItem item={item} onLike={handleLike} />
  ), [handleLike]);

  return <FlashList
    data={posts}
    renderItem={renderItem}
    estimatedItemSize={200}
    keyExtractor={(item) => item.id}
    getItemLayout={(_, index) => ({
      length: 200, offset: 200 * index, index
    })}
  />;
}

The Core Problem

Standard JS animations run on the JS thread. If the JS thread is busy (re-renders, API calls), animation frames get dropped. Solution: move animations to the UI thread.

Animation Libraries (Ranked by Performance)

// ✅ Reanimated 3 — runs 100% on UI thread
import Animated, { useSharedValue, useAnimatedStyle,
  withSpring, withTiming, runOnJS } from 'react-native-reanimated';

function LikeButton() {
  const scale = useSharedValue(1);

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ scale: scale.value }]
  }));

  const handlePress = () => {
    scale.value = withSpring(1.3, {}, () => {
      scale.value = withSpring(1);  // bounce back
      runOnJS(onLike)();  // call JS callback from UI thread
    });
  };

  return <Animated.View style={animatedStyle}>
    <TouchableOpacity onPress={handlePress}>
      <Text>❤️</Text>
    </TouchableOpacity>
  </Animated.View>;
}

Startup Time Optimizations

• Hermes engine: Enable Hermes (now default in RN 0.70+). It AOT-compiles JS to bytecode, reducing parse time by ~50%.
• Lazy navigation: Only load screen modules when navigated to, not at startup.
• Inline requires: Enable inlineRequires in Metro config — modules only load when first accessed.
• Splash screen: Use react-native-bootsplash to hide white flash during JS loading.
• RAM Bundles: Load JS modules on-demand from disk instead of loading the full bundle.

Bundle Size Reduction

• Tree shaking: Use named imports: import { debounce } from 'lodash-es' not import _ from 'lodash'.
• Analyze bundle: npx react-native bundle-visualizer — find what's eating your bundle.
• Replace heavy libraries: date-fns over moment.js (250kb → 20kb tree-shaken).
• Image optimization: Use WebP format, resize images at upload time, never ship full-resolution images.
• Codepush / OTA updates: Deliver JS updates without App Store review.

// metro.config.js — inline requires for lazy loading
module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        inlineRequires: true,  // modules load on first use
      },
    }),
  },
};

The 4 Causes of Unnecessary Re-renders

// ❌ Creates new array every render, kills memo
<PostList filters={['trending', 'new']} />

// ✅ Stable reference
const FILTERS = ['trending', 'new']; // outside component
<PostList filters={FILTERS} />

// ✅ useMemo for expensive computed values
const sortedPosts = useMemo(
  () => [...posts].sort((a, b) => b.likes - a.likes),
  [posts]  // only re-sort when posts array changes
);

// ✅ Correct React.memo with custom comparator
const Avatar = React.memo(({ user }) => (
  <Image source={{ uri: user.avatar }} />
), (prev, next) => prev.user.id === next.user.id);

Navigator Hierarchy

Auth Flow Pattern

function RootNavigator() {
  const { user, isLoading } = useAuthStore();

  if (isLoading) return <SplashScreen />;

  return <NavigationContainer linking={linkingConfig}>
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      {user ? (
        <Stack.Screen name="App" component={AppNavigator} />
      ) : (
        <Stack.Screen name="Auth" component={AuthNavigator} />
      )}
    </Stack.Navigator>
  </NavigationContainer>;
}

Deep Link Configuration

const linkingConfig = {
  prefixes: ['myapp://', 'https://myapp.com'],
  config: {
    screens: {
      App: {
        screens: {
          MainTab: {
            screens: {
              HomeStack: {
                screens: {
                  PostDetail: 'post/:postId',  // myapp://post/123
                }
              },
              ProfileStack: {
                screens: {
                  Profile: 'user/:username',
                }
              }
            }
          }
        }
      },
      Auth: {
        screens: {
          Login: 'login',
        }
      }
    }
  }
};

Architecture: Axios + Interceptors

// api/client.ts — Central API client
import axios from 'axios';

const apiClient = axios.create({
  baseURL: getApiBaseUrl(),
  timeout: 15000,
  headers: { 'Content-Type': 'application/json' },
});

// ── Request interceptor: inject auth token ──
apiClient.interceptors.request.use(async (config) => {
  const token = await getAccessToken();
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// ── Response interceptor: handle 401 token refresh ──
let isRefreshing = false;
let failedQueue = [];

apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    const original = error.config;

    if (error.response?.status === 401 && !original._retry) {
      if (isRefreshing) {
        // Queue requests while refreshing
        return new Promise((resolve, reject) => {
          failedQueue.push({ resolve, reject });
        }).then(token => {
          original.headers.Authorization = `Bearer ${token}`;
          return apiClient(original);
        });
      }

      original._retry = true;
      isRefreshing = true;

      try {
        const newToken = await refreshAccessToken();
        processQueue(null, newToken);  // retry queued requests
        original.headers.Authorization = `Bearer ${newToken}`;
        return apiClient(original);
      } catch (refreshError) {
        processQueue(refreshError, null);
        logout();  // force re-login
        return Promise.reject(refreshError);
      } finally {
        isRefreshing = false;
      }
    }
    return Promise.reject(error);
  }
);

Retry Logic for Network Failures

// Exponential backoff retry
import axiosRetry from 'axios-retry';

axiosRetry(apiClient, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,  // 1s, 2s, 4s
  retryCondition: (error) =>
    axiosRetry.isNetworkError(error) ||
    error.response?.status >= 500,  // retry server errors only
});

Cursor-based vs Offset Pagination

// React Query infinite scroll — clean pattern
const {
  data, fetchNextPage, hasNextPage, isFetchingNextPage
} = useInfiniteQuery({
  queryKey: ['feed'],
  queryFn: ({ pageParam = null }) =>
    fetchPosts({ cursor: pageParam, limit: 20 }),
  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
});

// Flatten pages for FlatList
const posts = useMemo(
  () => data?.pages.flatMap(page => page.posts) ?? [],
  [data]
);

return <FlashList
  data={posts}
  renderItem={renderItem}
  estimatedItemSize={200}
  onEndReached={() => {
    if (hasNextPage && !isFetchingNextPage)
      fetchNextPage();
  }}
  onEndReachedThreshold={0.3}   // trigger 30% before end
  ListFooterComponent={() =>
    isFetchingNextPage ? <ActivityIndicator /> : null
  }
/>;

Offline-First Architecture

Implementation: WatermelonDB (Recommended)

// WatermelonDB — designed for offline-first RN apps
// Lazy-loads, Observable queries, sync protocol built-in

import { synchronize } from '@nozbe/watermelondb/sync';

async function syncWithServer() {
  await synchronize({
    database,
    pullChanges: async ({ lastPulledAt }) => {
      const response = await api.get(`/sync?since=${lastPulledAt}`);
      return response.data; // { changes: {...}, timestamp: ... }
    },
    pushChanges: async ({ changes }) => {
      await api.post('/sync', { changes });
    },
  });
}

Conflict Resolution Strategies

• Last-Write-Wins (LWW): Use timestamps — the most recent write wins. Simple but can lose data.
• Server-Wins: Server's version always overrides local. Safe for financial data.
• Client-Wins: Local version overrides server. Good for user preferences.
• Merge: Combine both changes (e.g. CRDT for collaborative text). Complex but lossless.
• User prompt: Show the user both versions and let them choose. Last resort for important data.

Network State Detection

import NetInfo from '@react-native-community/netinfo';

function useNetworkSync() {
  useEffect(() => {
    const unsubscribe = NetInfo.addEventListener(state => {
      if (state.isConnected && state.isInternetReachable) {
        syncWithServer();  // trigger sync when back online
      }
    });
    return unsubscribe;
  }, []);
}

// ✅ Correct: react-native-keychain for tokens
import * as Keychain from 'react-native-keychain';

async function saveToken(token) {
  await Keychain.setGenericPassword('auth', token, {
    accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
    securityLevel: Keychain.SECURITY_LEVEL.SECURE_SOFTWARE,
  });
}

async function getToken() {
  const credentials = await Keychain.getGenericPassword();
  return credentials ? credentials.password : null;
}

Additional Security Measures

• Certificate pinning: Pin your API certificate to prevent MITM attacks. Use react-native-ssl-pinning.
• Root/Jailbreak detection: Use react-native-jail-monkey to detect compromised devices.
• Biometric auth: Use react-native-biometrics for Face ID / Fingerprint.
• Code obfuscation: Enable Hermes + ProGuard (Android) to make reverse engineering harder.
• Avoid logging sensitive data: Strip all console.log in production builds.

The Testing Pyramid for React Native

// Integration test with RNTL — test behavior, not implementation
import { render, fireEvent, waitFor } from '@testing-library/react-native';

describe('LoginScreen', () => {
  it('shows error when login fails', async () => {
    mockApi.post('/auth/login').replyOnce(401);

    const { getByPlaceholderText, getByText } = render(<LoginScreen />);

    fireEvent.changeText(getByPlaceholderText('Email'), 'bad@email.com');
    fireEvent.changeText(getByPlaceholderText('Password'), 'wrongpass');
    fireEvent.press(getByText('Login'));

    await waitFor(() => {
      expect(getByText('Invalid credentials')).toBeTruthy();
    });
  });
});

What to Test at Each Level

• Unit: Pure utility functions, custom hooks (renderHook), Redux reducers/selectors
• Integration: Screens with mock API, form validation, navigation flows, state changes
• E2E (Detox): Login → Feed → Like post → Logout; Payment flow; Onboarding

System Components

Key Design Decisions

• WebSocket for real-time: Persistent connection for message delivery. Fall back to polling if WS fails.
• Optimistic sending: Show message instantly with "pending" status, update to "sent" on server ack.
• Message deduplication: Client-generated UUID per message prevents duplicates on retry.
• Inverted FlatList: Use inverted={true} on FlatList — new messages at bottom, list grows up naturally.
• Read receipts: Emit read event when message is visible (use IntersectionObserver equivalent / FlatList viewableItems).
• Push notifications: When WS connection is closed (app backgrounded), use FCM/APNs push.

// Message with optimistic update pattern
function useSendMessage(chatId) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (content) => api.sendMessage(chatId, content),

    // Optimistic update — show message immediately
    onMutate: async (content) => {
      const tempMessage = {
        id: uuid(),          // client-generated ID
        content, chatId,
        status: 'pending',
        createdAt: new Date(),
      };
      queryClient.setQueryData(['messages', chatId], (old) => ({
        ...old, messages: [...old.messages, tempMessage]
      }));
      return { tempMessage };
    },

    // Replace temp message with server-confirmed message
    onSuccess: (serverMessage, _, { tempMessage }) => {
      queryClient.setQueryData(['messages', chatId], (old) => ({
        ...old, messages: old.messages.map(m =>
          m.id === tempMessage.id ? serverMessage : m
        )
      }));
    },

    onError: (_, __, { tempMessage }) => {
      // Mark as failed — show retry button
      queryClient.setQueryData(['messages', chatId], (old) => ({
        ...old, messages: old.messages.map(m =>
          m.id === tempMessage.id ? { ...m, status: 'failed' } : m
        )
      }));
    }
  });
}

Core Technical Challenges

• Only 1 video plays at a time, 2-3 are preloaded ahead
• Smooth swipe between full-screen videos (no jank)
• Memory management — can't keep all videos loaded
• Autoplay on scroll into view

Architecture

// PagerView or FlashList (vertical) — one item = full screen
import PagerView from 'react-native-pager-view';

function ReelsFeed() {
  const [activeIndex, setActiveIndex] = useState(0);

  return <PagerView
    style={styles.pager}
    orientation="vertical"
    onPageSelected={(e) => setActiveIndex(e.nativeEvent.position)}
  >
    {reels.map((reel, index) => (
      <ReelItem
        key={reel.id}
        reel={reel}
        // Only active ±1 items render video player
        isActive={index === activeIndex}
        shouldPreload={Math.abs(index - activeIndex) === 1}
      />
    ))}
  </PagerView>;
}

const ReelItem = React.memo(({ reel, isActive, shouldPreload }) => {
  return <View style={styles.fullScreen}>
    {(isActive || shouldPreload) && (
      <Video
        source={{ uri: reel.videoUrl }}
        paused={!isActive}       // pause when not visible
        repeat={isActive}        // loop only active video
        resizeMode="cover"
        onBuffer={() => showLoadingIndicator()}
      />
    )}
  </View>;
});

Performance Strategies

• Window: only render ±1 from active: Unmount videos 2+ away from active to free memory.
• Preload URLs: Pre-cache video URLs for the next 2 items using Video.prefetch(url).
• Thumbnail placeholder: Show static thumbnail until video loads to avoid black screen.
• CDN + adaptive bitrate: Serve HLS streams — mobile gets lower quality, WiFi gets HD.
• Background audio handling: Pause video when app goes to background, handle audio session.

Design Tokens → Components → Patterns

// 1. Design Tokens — single source of truth
const tokens = {
  colors: {
    primary: '#818cf8',
    surface: '#1e1e2e',
    text: { primary: '#e2e8f0', secondary: '#94a3b8' },
    semantic: { error: '#f87171', success: '#34d399' },
  },
  spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
  typography: {
    sizes: { xs: 11, sm: 13, md: 15, lg: 18, xl: 24 },
    weights: { regular: '400', semibold: '600', bold: '700' },
  },
  radii: { sm: 6, md: 10, lg: 16, full: 9999 },
};

// 2. Themed components using tokens
function Button({ variant = 'primary', size = 'md', label, onPress }) {
  const theme = useTheme();
  return <TouchableOpacity
    onPress={onPress}
    style={[styles.base, styles[variant], styles[`size_${size}`]]}
    accessibilityRole="button"
    accessibilityLabel={label}
  >
    <Text style={styles.label}>{label}</Text>
  </TouchableOpacity>;
}

// 3. Dark mode — swap token values, not component styles
const darkTheme = { ...tokens, colors: { ...tokens.colors, surface: '#0f0f1a' } };
const lightTheme = { ...tokens, colors: { ...tokens.colors, surface: '#ffffff' } };

Component Library Structure

• Atoms: Button, Text, Icon, Avatar, Badge, Input
• Molecules: Card, ListItem, SearchBar, FormField
• Organisms: Header, BottomSheet, Modal, PostCard
• Templates: AuthLayout, TabLayout, ModalLayout

Push Notification Architecture

// react-native-firebase/messaging — comprehensive solution
import messaging from '@react-native-firebase/messaging';

function setupNotifications() {
  // 1. Foreground notifications
  messaging().onMessage(async (remoteMessage) => {
    showInAppNotification(remoteMessage);
  });

  // 2. App opened from background tap
  messaging().onNotificationOpenedApp((remoteMessage) => {
    navigateToScreen(remoteMessage.data);
  });

  // 3. App opened from killed state
  messaging().getInitialNotification().then((remoteMessage) => {
    if (remoteMessage) navigateToScreen(remoteMessage.data);
  });

  // 4. Background handler (runs even when app is killed)
  messaging().setBackgroundMessageHandler(async (remoteMessage) => {
    updateBadgeCount(remoteMessage);
  });
}

Observability Stack

Key Performance Metrics to Track

• Time to Interactive (TTI): Time from launch to first meaningful user interaction.
• JS thread FPS: Target 60fps; drops below 55fps are noticeable to users.
• App start time: Cold start (first install/after killed) vs warm start (from background).
• Memory usage: Watch for memory leaks, especially with image-heavy screens.
• Crash-free sessions: Industry standard is 99.5%+ crash-free rate.

// Sentry performance tracing example
import * as Sentry from '@sentry/react-native';

// Measure a critical user flow
const transaction = Sentry.startTransaction({
  name: 'checkout.complete', op: 'user-action'
});

try {
  const span = transaction.startChild({ op: 'api.call', description: 'POST /orders' });
  const result = await createOrder(cart);
  span.finish();
} finally {
  transaction.finish();
}