features/
  checkout/
    components/
      checkout-summary.tsx
      checkout-item-row.tsx
    hooks/
      use-checkout.hook.ts
    services/
      checkout.service.ts
    store/
      checkout.store.ts
    types/
      checkout.types.ts
    screens/
      checkout-review.screen.tsx

app/
components/
  ui/
  shared/
  screens/
  profile/
  settings/
hooks/
  auth/
  profile/
services/
  auth/
  profile/
features/
  checkout/           # Large enough to warrant isolation
    components/
    hooks/
    services/
    store/
    types/

app/                    # Expo Router file-based routes
components/
  ui/                   # Primitives: Button, Input, Card
  shared/               # Cross-domain composites
  screens/              # Screen composition sections
  <domain>/             # Domain-owned components
hooks/
  <domain>/
  native/               # Platform-specific hooks
services/
  <domain>/
store/
  <domain>/
constants/
  <domain>/
types/
  <domain>/
lib/
  <concern>/
assets/
  images/
  fonts/
plugins/                # Expo config plugins

hooks/
  auth/
    use-auth.hook.ts
    use-session.hook.ts
  profile/
    use-profile.hook.ts
  native/
    use-permissions.hook.ts
    use-app-state.hook.ts

app/
  _layout.tsx           # Root layout (wraps all routes)
  index.tsx             # "/" — home screen
  settings.tsx          # "/settings"
  [id].tsx              # "/123" — dynamic segment
  [...missing].tsx      # Catch-all for 404

app/
  (tabs)/
    _layout.tsx         # Tab navigator layout
    index.tsx           # "/" — first tab
    explore.tsx         # "/explore" — second tab
    profile.tsx         # "/profile" — third tab
  (auth)/
    _layout.tsx         # Auth stack layout
    login.tsx           # "/login"
    register.tsx        # "/register"
    forgot-password.tsx # "/forgot-password"
  (modals)/
    _layout.tsx         # Modal presentation stack
    confirm.tsx         # "/confirm"

app/
  products/
    [id].tsx            # "/products/123"
    [id]/
      reviews.tsx       # "/products/123/reviews"
  users/
    [userId]/
      posts/
        [postId].tsx    # "/users/42/posts/7"

import { useLocalSearchParams } from "expo-router";
 
export default function ProductScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  // ...
}

import { ProfileHeader } from "@/components/screens/profile-header.screen";
import { ProfileActivity } from "@/components/screens/profile-activity.screen";
import { ProfileStats } from "@/components/screens/profile-stats.screen";
import { ScreenContainer } from "@/components/ui/screen-container";
 
export default function ProfileScreen() {
  return (
    <ScreenContainer>
      <ProfileHeader />
      <ProfileStats />
      <ProfileActivity />
    </ScreenContainer>
  );
}

app/
  api/
    auth+api.ts         # POST /api/auth
    users/[id]+api.ts   # GET /api/users/123

// app/_layout.tsx
import { Stack } from "expo-router";
import { ThemeProvider } from "@/store/app/theme-provider";
import { AuthProvider } from "@/store/auth/auth-provider";
 
export default function RootLayout() {
  return (
    <ThemeProvider>
      <AuthProvider>
        <Stack screenOptions={{ headerShown: false }}>
          <Stack.Screen name="(tabs)" />
          <Stack.Screen name="(auth)" />
          <Stack.Screen
            name="(modals)"
            options={{ presentation: "modal" }}
          />
        </Stack>
      </AuthProvider>
    </ThemeProvider>
  );
}

// app/(tabs)/_layout.tsx
import { Tabs } from "expo-router";
import { Home, Search, User } from "lucide-react-native";
 
export default function TabLayout() {
  return (
    <Tabs
      screenOptions={{
        tabBarActiveTintColor: "#007AFF",
        headerShown: false,
      }}
    >
      <Tabs.Screen
        name="index"
        options={{
          title: "Home",
          tabBarIcon: ({ color, size }) => <Home color={color} size={size} />,
        }}
      />
      <Tabs.Screen
        name="explore"
        options={{
          title: "Explore",
          tabBarIcon: ({ color, size }) => <Search color={color} size={size} />,
        }}
      />
      <Tabs.Screen
        name="profile"
        options={{
          title: "Profile",
          tabBarIcon: ({ color, size }) => <User color={color} size={size} />,
        }}
      />
    </Tabs>
  );
}

// app/(auth)/_layout.tsx
import { Stack } from "expo-router";
 
export default function AuthLayout() {
  return (
    <Stack
      screenOptions={{
        headerBackTitle: "Back",
        headerStyle: { backgroundColor: "#f8f9fa" },
      }}
    >
      <Stack.Screen name="login" options={{ title: "Sign In" }} />
      <Stack.Screen name="register" options={{ title: "Create Account" }} />
      <Stack.Screen name="forgot-password" options={{ title: "Reset Password" }} />
    </Stack>
  );
}

// app/(drawer)/_layout.tsx
import { Drawer } from "expo-router/drawer";
 
export default function DrawerLayout() {
  return (
    <Drawer>
      <Drawer.Screen name="index" options={{ title: "Dashboard" }} />
      <Drawer.Screen name="settings" options={{ title: "Settings" }} />
      <Drawer.Screen name="help" options={{ title: "Help & Support" }} />
    </Drawer>
  );
}

import { Redirect, Stack } from "expo-router";
import { useAuth } from "@/hooks/auth/use-auth.hook";
 
export default function ProtectedLayout() {
  const { isAuthenticated } = useAuth();
 
  if (!isAuthenticated) {
    return <Redirect href="/login" />;
  }
 
  return <Stack />;
}

components/
  profile/
    profile-header.tsx
    profile-stats-card.tsx
    profile-activity-list.tsx
    profile-edit-form.tsx
    profile-avatar-picker.tsx
  orders/
    order-card.tsx
    order-status-badge.tsx
    order-timeline.tsx
    order-summary.tsx
  products/
    product-card.tsx
    product-gallery.tsx
    product-variant-picker.tsx
    product-review-item.tsx

// components/orders/order-card.tsx
import { View, Text, Pressable, StyleSheet } from "react-native";
import { useRouter } from "expo-router";
import { Card } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";
import type { Order } from "@/types/orders/order.types";
 
type OrderCardProps = {
  order: Order;
};
 
export function OrderCard({ order }: OrderCardProps) {
  const router = useRouter();
 
  return (
    <Pressable onPress={() => router.push(`/orders/${order.id}`)}>
      <Card>
        <View style={styles.header}>
          <Text style={styles.orderId}>#{order.number}</Text>
          <Badge label={order.status} variant={statusVariant(order.status)} />
        </View>
        <Text style={styles.date}>{formatOrderDate(order.createdAt)}</Text>
        <Text style={styles.total}>${order.total.toFixed(2)}</Text>
      </Card>
    </Pressable>
  );
}

import { OrderCard } from "@/components/orders/order-card";
import { ProductCard } from "@/components/products/product-card";

components/
  profile/
    profile-header.tsx          # Shared logic
    profile-header.ios.tsx      # iOS-specific rendering
    profile-header.android.tsx  # Android-specific rendering

components/
  profile/
    profile-header.tsx
    profile-stats-card.tsx
    profile.styles.ts           # Only if styles are genuinely shared

components/
  screens/
    home-hero.screen.tsx
    home-featured-products.screen.tsx
    home-categories.screen.tsx
    profile-header.screen.tsx
    profile-activity.screen.tsx
    profile-stats.screen.tsx
    settings-account.screen.tsx
    settings-notifications.screen.tsx
    settings-privacy.screen.tsx

// app/(tabs)/index.tsx
import { ScreenContainer } from "@/components/ui/screen-container";
import { HomeHero } from "@/components/screens/home-hero.screen";
import { HomeFeaturedProducts } from "@/components/screens/home-featured-products.screen";
import { HomeCategories } from "@/components/screens/home-categories.screen";
 
export default function HomeScreen() {
  return (
    <ScreenContainer>
      <HomeHero />
      <HomeFeaturedProducts />
      <HomeCategories />
    </ScreenContainer>
  );
}

// components/screens/home-featured-products.screen.tsx
import { View, FlatList, StyleSheet } from "react-native";
import { SectionHeader } from "@/components/shared/section-header.shared";
import { ProductCard } from "@/components/products/product-card";
import { useFeaturedProducts } from "@/hooks/products/use-featured-products.hook";
import { ErrorFallback } from "@/components/shared/error-fallback.shared";
import { Skeleton } from "@/components/ui/skeleton";
 
export function HomeFeaturedProducts() {
  const { products, isLoading, error, refetch } = useFeaturedProducts();
 
  if (isLoading) return <FeaturedProductsSkeleton />;
  if (error) return <ErrorFallback message="Could not load products." onRetry={refetch} />;
 
  return (
    <View style={styles.container}>
      <SectionHeader title="Featured" actionLabel="See All" onAction={() => {}} />
      <FlatList
        horizontal
        data={products}
        keyExtractor={(item) => item.id}
        renderItem={({ item }) => <ProductCard product={item} />}
        showsHorizontalScrollIndicator={false}
        contentContainerStyle={styles.list}
      />
    </View>
  );
}
 
function FeaturedProductsSkeleton() {
  return (
    <View style={styles.container}>
      <Skeleton width="40%" height={24} />
      <View style={styles.skeletonRow}>
        {[1, 2, 3].map((i) => (
          <Skeleton key={i} width={160} height={200} borderRadius={12} />
        ))}
      </View>
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { gap: 12, paddingVertical: 16 },
  list: { gap: 12 },
  skeletonRow: { flexDirection: "row", gap: 12 },
});

// components/shared/empty-state.shared.tsx
import { View, Text, StyleSheet } from "react-native";
import { Button } from "@/components/ui/button";
 
type EmptyStateProps = {
  icon?: React.ReactNode;
  title: string;
  description?: string;
  actionLabel?: string;
  onAction?: () => void;
};
 
export function EmptyState({
  icon,
  title,
  description,
  actionLabel,
  onAction,
}: EmptyStateProps) {
  return (
    <View style={styles.container} accessibilityRole="text">
      {icon && <View style={styles.icon}>{icon}</View>}
      <Text style={styles.title}>{title}</Text>
      {description && <Text style={styles.description}>{description}</Text>}
      {actionLabel && onAction && (
        <Button title={actionLabel} onPress={onAction} variant="secondary" />
      )}
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { alignItems: "center", padding: 32, gap: 12 },
  icon: { marginBottom: 8 },
  title: { fontSize: 18, fontWeight: "600", textAlign: "center" },
  description: { fontSize: 14, color: "#666", textAlign: "center" },
});

// components/shared/error-fallback.shared.tsx
import { View, Text, StyleSheet } from "react-native";
import { Button } from "@/components/ui/button";
 
type ErrorFallbackProps = {
  message?: string;
  onRetry?: () => void;
};
 
export function ErrorFallback({
  message = "Something went wrong.",
  onRetry,
}: ErrorFallbackProps) {
  return (
    <View style={styles.container}>
      <Text style={styles.message}>{message}</Text>
      {onRetry && <Button title="Try Again" onPress={onRetry} variant="secondary" />}
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, alignItems: "center", justifyContent: "center", padding: 24, gap: 16 },
  message: { fontSize: 16, color: "#333", textAlign: "center" },
});

// components/ui/button.tsx
import { Pressable, Text, ActivityIndicator, StyleSheet } from "react-native";
import * as Haptics from "expo-haptics";
 
type ButtonProps = {
  title: string;
  onPress: () => void;
  variant?: "primary" | "secondary" | "ghost";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
  disabled?: boolean;
};
 
export function Button({
  title,
  onPress,
  variant = "primary",
  size = "md",
  loading = false,
  disabled = false,
}: ButtonProps) {
  const handlePress = () => {
    Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
    onPress();
  };
 
  return (
    <Pressable
      onPress={handlePress}
      disabled={disabled || loading}
      style={({ pressed }) => [
        styles.base,
        styles[variant],
        styles[size],
        pressed && styles.pressed,
        disabled && styles.disabled,
      ]}
      accessibilityRole="button"
      accessibilityState={{ disabled: disabled || loading }}
    >
      {loading ? (
        <ActivityIndicator color={variant === "primary" ? "#fff" : "#007AFF"} />
      ) : (
        <Text style={[styles.text, styles[`${variant}Text`]]}>{title}</Text>
      )}
    </Pressable>
  );
}

// components/ui/screen-container.tsx
import { ScrollView, StyleSheet, ViewStyle } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
 
type ScreenContainerProps = {
  children: React.ReactNode;
  scrollable?: boolean;
  style?: ViewStyle;
};
 
export function ScreenContainer({
  children,
  scrollable = true,
  style,
}: ScreenContainerProps) {
  const content = scrollable ? (
    <ScrollView
      contentContainerStyle={styles.scroll}
      showsVerticalScrollIndicator={false}
    >
      {children}
    </ScrollView>
  ) : (
    children
  );
 
  return (
    <SafeAreaView style={[styles.container, style]}>
      {content}
    </SafeAreaView>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: "#fff" },
  scroll: { paddingHorizontal: 16, paddingBottom: 32 },
});

hooks/
  auth/
    use-auth.hook.ts
    use-session.hook.ts
    use-biometric-auth.hook.ts
  profile/
    use-profile.hook.ts
    use-profile-edit.hook.ts
  products/
    use-product-search.hook.ts
    use-product-filter.hook.ts
    use-featured-products.hook.ts
  orders/
    use-orders.hook.ts
    use-order-tracking.hook.ts
  cart/
    use-cart.hook.ts
    use-cart-actions.hook.ts

// hooks/products/use-product-search.hook.ts
import { useState, useCallback } from "react";
import { useDebounce } from "@/lib/timing/use-debounce.lib";
import { searchProducts } from "@/services/products/product.service";
import type { Product } from "@/types/products/product.types";
 
export function useProductSearch() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<Product[]>([]);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
 
  const search = useCallback(async (searchQuery: string) => {
    if (!searchQuery.trim()) {
      setResults([]);
      return;
    }
    setIsLoading(true);
    setError(null);
    try {
      const data = await searchProducts(searchQuery);
      setResults(data);
    } catch (err) {
      setError("Failed to search products.");
      setResults([]);
    } finally {
      setIsLoading(false);
    }
  }, []);
 
  const clearSearch = useCallback(() => {
    setQuery("");
    setResults([]);
    setError(null);
  }, []);
 
  return { query, setQuery, results, isLoading, error, clearSearch };
}

// hooks/orders/use-orders.hook.ts
import { useQuery } from "@tanstack/react-query";
import { fetchOrders } from "@/services/orders/order.service";
import type { OrderFilters } from "@/types/orders/order.types";
 
export function useOrders(filters: OrderFilters) {
  return useQuery({
    queryKey: ["orders", filters],
    queryFn: () => fetchOrders(filters),
    staleTime: 1000 * 60 * 5,
  });
}

hooks/
  native/
    use-permissions.hook.ts
    use-app-state.hook.ts
    use-keyboard.hook.ts
    use-network.hook.ts
    use-device-info.hook.ts
    use-haptics.hook.ts
    use-notifications.hook.ts
    use-camera.hook.ts
    use-location.hook.ts
    use-biometrics.hook.ts

// hooks/native/use-permissions.hook.ts
import { useState, useCallback } from "react";
import * as ImagePicker from "expo-image-picker";
import { Alert, Linking } from "react-native";
 
type PermissionType = "camera" | "mediaLibrary" | "location" | "notifications";
 
export function usePermission(type: PermissionType) {
  const [status, setStatus] = useState<"undetermined" | "granted" | "denied">("undetermined");
 
  const request = useCallback(async () => {
    let requestFn: () => Promise<{ granted: boolean; canAskAgain: boolean }>;
 
    switch (type) {
      case "camera":
        requestFn = ImagePicker.requestCameraPermissionsAsync;
        break;
      case "mediaLibrary":
        requestFn = ImagePicker.requestMediaLibraryPermissionsAsync;
        break;
      default:
        throw new Error(`Permission type "${type}" not implemented`);
    }
 
    const result = await requestFn();
    setStatus(result.granted ? "granted" : "denied");
 
    if (!result.granted && !result.canAskAgain) {
      Alert.alert(
        "Permission Required",
        `Please enable ${type} access in your device settings.`,
        [
          { text: "Cancel", style: "cancel" },
          { text: "Open Settings", onPress: () => Linking.openSettings() },
        ]
      );
    }
 
    return result.granted;
  }, [type]);
 
  return { status, request, isGranted: status === "granted" };
}

// hooks/native/use-app-state.hook.ts
import { useEffect, useRef, useState } from "react";
import { AppState, type AppStateStatus } from "react-native";
 
export function useAppState() {
  const [appState, setAppState] = useState<AppStateStatus>(AppState.currentState);
  const previousState = useRef(appState);
 
  useEffect(() => {
    const subscription = AppState.addEventListener("change", (nextState) => {
      previousState.current = appState;
      setAppState(nextState);
    });
    return () => subscription.remove();
  }, [appState]);
 
  return {
    appState,
    previousState: previousState.current,
    isActive: appState === "active",
    isBackground: appState === "background",
    cameFromBackground:
      previousState.current.match(/inactive|background/) !== null && appState === "active",
  };
}

// hooks/native/use-keyboard.hook.ts
import { useEffect, useState } from "react";
import { Keyboard, Platform, type KeyboardEvent } from "react-native";
 
export function useKeyboard() {
  const [isVisible, setIsVisible] = useState(false);
  const [height, setHeight] = useState(0);
 
  useEffect(() => {
    const showEvent = Platform.OS === "ios" ? "keyboardWillShow" : "keyboardDidShow";
    const hideEvent = Platform.OS === "ios" ? "keyboardWillHide" : "keyboardDidHide";
 
    const showSub = Keyboard.addListener(showEvent, (e: KeyboardEvent) => {
      setIsVisible(true);
      setHeight(e.endCoordinates.height);
    });
    const hideSub = Keyboard.addListener(hideEvent, () => {
      setIsVisible(false);
      setHeight(0);
    });
 
    return () => {
      showSub.remove();
      hideSub.remove();
    };
  }, []);
 
  return { isVisible, height, dismiss: Keyboard.dismiss };
}

services/
  app/
    api-client.service.ts       # Shared fetch wrapper
  auth/
    auth.service.ts
  products/
    product.service.ts
  orders/
    order.service.ts
  profile/
    profile.service.ts

// services/app/api-client.service.ts
import { getAuthToken } from "@/store/auth/auth.store";
import Constants from "expo-constants";
 
const BASE_URL = Constants.expoConfig?.extra?.apiUrl ?? "https://api.example.com";
 
type RequestOptions = {
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  body?: unknown;
  headers?: Record<string, string>;
};
 
export async function apiClient<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { method = "GET", body, headers = {} } = options;
  const token = getAuthToken();
 
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method,
    headers: {
      "Content-Type": "application/json",
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
      ...headers,
    },
    ...(body ? { body: JSON.stringify(body) } : {}),
  });
 
  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new ApiError(response.status, error.message ?? "Request failed");
  }
 
  return response.json();
}
 
export class ApiError extends Error {
  constructor(public status: number, message: string) {
    super(message);
    this.name = "ApiError";
  }
}

// services/products/product.service.ts
import { apiClient } from "@/services/app/api-client.service";
import type { Product, ProductFilters } from "@/types/products/product.types";
 
export async function fetchProducts(filters: ProductFilters): Promise<Product[]> {
  const params = new URLSearchParams();
  if (filters.category) params.set("category", filters.category);
  if (filters.query) params.set("q", filters.query);
  if (filters.page) params.set("page", String(filters.page));
 
  return apiClient<Product[]>(`/products?${params.toString()}`);
}
 
export async function fetchProduct(id: string): Promise<Product> {
  return apiClient<Product>(`/products/${id}`);
}
 
export async function searchProducts(query: string): Promise<Product[]> {
  return apiClient<Product[]>(`/products/search?q=${encodeURIComponent(query)}`);
}

// services/orders/order.service.ts
import { apiClient } from "@/services/app/api-client.service";
import type { Order } from "@/types/orders/order.types";
 
type ApiOrder = {
  order_id: string;
  order_number: number;
  created_at: string;
  total_cents: number;
  status: string;
};
 
function toOrder(raw: ApiOrder): Order {
  return {
    id: raw.order_id,
    number: raw.order_number,
    createdAt: new Date(raw.created_at),
    total: raw.total_cents / 100,
    status: raw.status as Order["status"],
  };
}
 
export async function fetchOrders(): Promise<Order[]> {
  const raw = await apiClient<ApiOrder[]>("/orders");
  return raw.map(toOrder);
}

services/
  app/
    storage.service.ts          # Unified storage interface
    secure-storage.service.ts   # Expo SecureStore wrapper
  auth/
    auth-storage.service.ts     # Token persistence
  preferences/
    preferences-storage.service.ts

// services/app/storage.service.ts
import { MMKV } from "react-native-mmkv";
 
const storage = new MMKV();
 
export const StorageService = {
  getString(key: string): string | undefined {
    return storage.getString(key);
  },
  setString(key: string, value: string): void {
    storage.set(key, value);
  },
  getObject<T>(key: string): T | undefined {
    const json = storage.getString(key);
    if (!json) return undefined;
    try { return JSON.parse(json) as T; }
    catch { return undefined; }
  },
  setObject<T>(key: string, value: T): void {
    storage.set(key, JSON.stringify(value));
  },
  delete(key: string): void {
    storage.delete(key);
  },
  clearAll(): void {
    storage.clearAll();
  },
};

// services/app/secure-storage.service.ts
import * as SecureStore from "expo-secure-store";
 
export const SecureStorageService = {
  async get(key: string): Promise<string | null> {
    return SecureStore.getItemAsync(key);
  },
  async set(key: string, value: string): Promise<void> {
    await SecureStore.setItemAsync(key, value);
  },
  async delete(key: string): Promise<void> {
    await SecureStore.deleteItemAsync(key);
  },
};

// services/auth/auth-storage.service.ts
import { SecureStorageService } from "@/services/app/secure-storage.service";
 
const TOKEN_KEY = "auth_token";
const REFRESH_TOKEN_KEY = "auth_refresh_token";
 
export const AuthStorageService = {
  async getToken(): Promise<string | null> {
    return SecureStorageService.get(TOKEN_KEY);
  },
  async setToken(token: string): Promise<void> {
    await SecureStorageService.set(TOKEN_KEY, token);
  },
  async clearTokens(): Promise<void> {
    await SecureStorageService.delete(TOKEN_KEY);
    await SecureStorageService.delete(REFRESH_TOKEN_KEY);
  },
};

store/
  app/
    theme.store.ts
    app.store.ts
  auth/
    auth.store.ts
  cart/
    cart.store.ts
  notifications/
    notifications.store.ts

// store/cart/cart.store.ts
import { create } from "zustand";
import type { CartItem } from "@/types/cart/cart.types";
 
type CartState = {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  updateQuantity: (id: string, quantity: number) => void;
  clearCart: () => void;
  totalItems: () => number;
  totalPrice: () => number;
};
 
export const useCartStore = create<CartState>((set, get) => ({
  items: [],
  addItem: (item) =>
    set((state) => {
      const existing = state.items.find((i) => i.id === item.id);
      if (existing) {
        return {
          items: state.items.map((i) =>
            i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i
          ),
        };
      }
      return { items: [...state.items, { ...item, quantity: 1 }] };
    }),
  removeItem: (id) =>
    set((state) => ({ items: state.items.filter((i) => i.id !== id) })),
  updateQuantity: (id, quantity) =>
    set((state) => ({
      items: state.items.map((i) => (i.id === id ? { ...i, quantity } : i)),
    })),
  clearCart: () => set({ items: [] }),
  totalItems: () => get().items.reduce((sum, i) => sum + i.quantity, 0),
  totalPrice: () => get().items.reduce((sum, i) => sum + i.price * i.quantity, 0),
}));

// store/cart/cart.store.ts
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
import { MMKV } from "react-native-mmkv";
 
const storage = new MMKV();
 
const mmkvStorage = {
  getItem: (name: string) => storage.getString(name) ?? null,
  setItem: (name: string, value: string) => storage.set(name, value),
  removeItem: (name: string) => storage.delete(name),
};
 
type CartState = {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  clearCart: () => void;
};
 
export const useCartStore = create<CartState>()(
  persist(
    (set) => ({
      items: [],
      addItem: (item) => set((state) => ({ items: [...state.items, item] })),
      clearCart: () => set({ items: [] }),
    }),
    {
      name: "cart-store",
      storage: createJSONStorage(() => mmkvStorage),
    }
  )
);

// store/app/mutation-queue.store.ts
import { create } from "zustand";
import NetInfo from "@react-native-community/netinfo";
 
type PendingMutation = {
  id: string;
  endpoint: string;
  method: "POST" | "PUT" | "DELETE";
  body: unknown;
  createdAt: number;
};
 
type MutationQueueState = {
  pending: PendingMutation[];
  enqueue: (mutation: Omit<PendingMutation, "id" | "createdAt">) => void;
  dequeue: (id: string) => void;
  flush: () => Promise<void>;
};
 
export const useMutationQueue = create<MutationQueueState>()((set, get) => ({
  pending: [],
  enqueue: (mutation) =>
    set((state) => ({
      pending: [
        ...state.pending,
        { ...mutation, id: crypto.randomUUID(), createdAt: Date.now() },
      ],
    })),
  dequeue: (id) =>
    set((state) => ({ pending: state.pending.filter((m) => m.id !== id) })),
  flush: async () => {
    const { pending, dequeue } = get();
    const netState = await NetInfo.fetch();
    if (!netState.isConnected) return;
 
    for (const mutation of pending) {
      try {
        await fetch(mutation.endpoint, {
          method: mutation.method,
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(mutation.body),
        });
        dequeue(mutation.id);
      } catch {
        break;
      }
    }
  },
}));

// hooks/orders/use-cancel-order.hook.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { cancelOrder } from "@/services/orders/order.service";
import type { Order } from "@/types/orders/order.types";
 
export function useCancelOrder() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: cancelOrder,
    onMutate: async (orderId: string) => {
      await queryClient.cancelQueries({ queryKey: ["orders"] });
      const previous = queryClient.getQueryData<Order[]>(["orders"]);
      queryClient.setQueryData<Order[]>(["orders"], (old) =>
        old?.map((order) =>
          order.id === orderId ? { ...order, status: "cancelled" } : order
        )
      );
      return { previous };
    },
    onError: (_err, _id, context) => {
      if (context?.previous) {
        queryClient.setQueryData(["orders"], context.previous);
      }
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ["orders"] });
    },
  });
}

app/
  (tabs)/               # Tab-based navigation group
    _layout.tsx
    index.tsx            # "/"
    search.tsx           # "/search"
  (auth)/               # Authentication flow group
    _layout.tsx
    login.tsx            # "/login"
    register.tsx         # "/register"
  (settings)/           # Settings stack group
    _layout.tsx
    index.tsx            # "/settings"
    notifications.tsx    # "/notifications"

app/
  products/
    _layout.tsx          # Stack navigator for products
    index.tsx            # "/products"
    [id].tsx             # "/products/123"
    [id]/
      reviews.tsx        # "/products/123/reviews"
      edit.tsx           # "/products/123/edit"

app/
  (modals)/
    _layout.tsx          # Stack with presentation: "modal"
    confirm-delete.tsx   # "/confirm-delete" (presented as modal)
    image-viewer.tsx     # "/image-viewer" (presented as modal)

// app/(modals)/_layout.tsx
import { Stack } from "expo-router";
 
export default function ModalLayout() {
  return (
    <Stack screenOptions={{ presentation: "modal", headerShown: false }}>
      <Stack.Screen name="confirm-delete" />
      <Stack.Screen name="image-viewer" />
    </Stack>
  );
}

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      ["expo-router", { "origin": "https://myapp.com" }]
    ]
  }
}

// app/products/[id].tsx
import { useLocalSearchParams } from "expo-router";
 
type ProductParams = {
  id: string;
};
 
export default function ProductScreen() {
  const { id } = useLocalSearchParams<ProductParams>();
  // id is typed as string
}

// app/users/[userId]/posts/[postId].tsx
import { useLocalSearchParams } from "expo-router";
 
type PostParams = {
  userId: string;
  postId: string;
};
 
export default function PostScreen() {
  const { userId, postId } = useLocalSearchParams<PostParams>();
}

import { useRouter } from "expo-router";
 
export function ProductCard({ productId }: { productId: string }) {
  const router = useRouter();
 
  return (
    <Pressable
      onPress={() =>
        router.push({
          pathname: "/products/[id]",
          params: { id: productId },
        })
      }
    >
      {/* ... */}
    </Pressable>
  );
}

import { Link } from "expo-router";
 
export function ProductLink({ id, name }: { id: string; name: string }) {
  return (
    <Link
      href={{
        pathname: "/products/[id]",
        params: { id },
      }}
    >
      {name}
    </Link>
  );
}

// types/navigation/routes.types.ts
export type RouteParams = {
  "/products/[id]": { id: string };
  "/users/[userId]/posts/[postId]": { userId: string; postId: string };
  "/orders/[orderId]": { orderId: string };
  "/search": { q?: string; category?: string };
};

// hooks/products/use-product-params.hook.ts
import { useLocalSearchParams } from "expo-router";
 
export function useProductParams() {
  const { id } = useLocalSearchParams<{ id: string }>();
 
  if (!id) {
    throw new Error("Product ID is required");
  }
 
  return { productId: id };
}

export function useOrderParams() {
  const { orderId } = useLocalSearchParams<{ orderId: string }>();
 
  const parsed = Number(orderId);
  if (Number.isNaN(parsed)) {
    throw new Error("Invalid order ID");
  }
 
  return { orderId: parsed };
}

// Navigating with query params
router.push({
  pathname: "/search",
  params: { q: "shoes", category: "footwear" },
});
 
// Reading query params
const { q, category } = useLocalSearchParams<{ q?: string; category?: string }>();

components/
  ui/
  shared/
  screens/
  order-history/        # Domain with hyphen
hooks/
  auth/
  native/
services/
  push-notifications/   # Domain with hyphen

// File: components/profile/profile-header.tsx
// Export: ProfileHeader
 
export function ProfileHeader() { /* ... */ }

components/
  orders/
    order-card.tsx           # Not "card.tsx"
    order-status-badge.tsx   # Not "status-badge.tsx"
    order-timeline.tsx       # Not "timeline.tsx"

import { OrderCard } from "@/components/orders/order-card";
import { ProductCard } from "@/components/products/product-card";

Is the file a component?
  ├── In components/ui/ → No suffix (button.tsx)
  ├── In components/shared/ → .shared.tsx
  ├── In components/screens/ → .screen.tsx
  └── In components/<domain>/ → No suffix (order-card.tsx)
 
Is the file logic?
  ├── React hook → .hook.ts
  ├── API/external call → .service.ts
  ├── State management → .store.ts
  └── Pure utility → .lib.ts
 
Is the file data/config?
  ├── Type definitions → .types.ts
  ├── Constants → .constants.ts
  ├── Validation → .schema.ts
  └── Expo plugin → .plugin.js

components/
  orders/
    order-card.tsx
    order-list.tsx
    order-detail-header.tsx
  screens/
    orders-list.screen.tsx
    order-detail.screen.tsx
hooks/
  orders/
    use-orders.hook.ts
    use-order-detail.hook.ts
    use-order-actions.hook.ts
services/
  orders/
    order.service.ts
store/
  orders/
    order.store.ts
types/
  orders/
    order.types.ts
constants/
  orders/
    order.constants.ts

// components/products/product-detail.tsx — 250 lines
export function ProductDetail({ product }: { product: Product }) {
  const [selectedVariant, setSelectedVariant] = useState(product.variants[0]);
  const [quantity, setQuantity] = useState(1);
  const { addItem } = useCartStore();
  const [showReviews, setShowReviews] = useState(false);
 
  return (
    <ScrollView>
      {/* 40 lines: image gallery */}
      {/* 30 lines: product info */}
      {/* 40 lines: variant picker */}
      {/* 20 lines: quantity selector */}
      {/* 30 lines: add to cart button with loading */}
      {/* 50 lines: reviews section */}
    </ScrollView>
  );
}

// components/products/product-detail.tsx — 30 lines
export function ProductDetail({ product }: { product: Product }) {
  const { selectedVariant, setSelectedVariant, quantity, setQuantity, addToCart, isAdding } =
    useProductActions(product);
 
  return (
    <ScrollView>
      <ProductGallery images={product.images} />
      <ProductInfo product={product} />
      <ProductVariantPicker
        variants={product.variants}
        selected={selectedVariant}
        onSelect={setSelectedVariant}
      />
      <QuantitySelector value={quantity} onChange={setQuantity} />
      <AddToCartButton onPress={addToCart} loading={isAdding} />
      <ProductReviews productId={product.id} />
    </ScrollView>
  );
}

// hooks/products/use-product-actions.hook.ts
export function useProductActions(product: Product) {
  const [selectedVariant, setSelectedVariant] = useState(product.variants[0]);
  const [quantity, setQuantity] = useState(1);
  const [isAdding, setIsAdding] = useState(false);
  const addItem = useCartStore((s) => s.addItem);
 
  const addToCart = useCallback(async () => {
    setIsAdding(true);
    try {
      addItem({ ...selectedVariant, quantity });
      Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
    } finally {
      setIsAdding(false);
    }
  }, [selectedVariant, quantity, addItem]);
 
  return { selectedVariant, setSelectedVariant, quantity, setQuantity, addToCart, isAdding };
}

components/
  products/
    product-detail.tsx           # Parent compositor
    product-gallery.tsx          # Image carousel
    product-info.tsx             # Title, price, description
    product-variant-picker.tsx   # Size/color selector
    product-reviews.tsx          # Reviews list

components/
  media/
    media-player.tsx             # Shared interface/logic
    media-player.ios.tsx         # iOS AVPlayer implementation
    media-player.android.tsx     # Android ExoPlayer implementation

// app/(tabs)/profile.tsx — 400+ lines
export default function ProfileScreen() {
  const { user, isLoading } = useProfile();
  const { posts, loadMore } = useUserPosts(user?.id);
  const [activeTab, setActiveTab] = useState("posts");
 
  if (isLoading) return <LoadingOverlay />;
 
  return (
    <ScrollView>
      {/* 50 lines of header markup */}
      <View>
        <Image source={{ uri: user.avatar }} />
        <Text>{user.name}</Text>
        <Text>{user.bio}</Text>
        <View style={styles.statsRow}>
          {/* 30 lines of stats */}
        </View>
        <Button title="Edit Profile" onPress={...} />
      </View>
 
      {/* 40 lines of tab bar */}
      <View style={styles.tabs}>
        {/* tab buttons */}
      </View>
 
      {/* 100+ lines of content based on active tab */}
      {activeTab === "posts" && (
        <FlatList data={posts} renderItem={...} />
      )}
      {activeTab === "saved" && (
        <SavedItemsList userId={user.id} />
      )}
 
      {/* 50 lines of footer */}
    </ScrollView>
  );
}

// app/(tabs)/profile.tsx — 20 lines
import { ScreenContainer } from "@/components/ui/screen-container";
import { ProfileHeader } from "@/components/screens/profile-header.screen";
import { ProfileTabs } from "@/components/screens/profile-tabs.screen";
 
export default function ProfileScreen() {
  return (
    <ScreenContainer>
      <ProfileHeader />
      <ProfileTabs />
    </ScreenContainer>
  );
}

// components/screens/profile-header.screen.tsx
import { View, Text, Image, StyleSheet } from "react-native";
import { Button } from "@/components/ui/button";
import { useProfile } from "@/hooks/profile/use-profile.hook";
import { Skeleton } from "@/components/ui/skeleton";
 
export function ProfileHeader() {
  const { user, isLoading } = useProfile();
 
  if (isLoading) return <ProfileHeaderSkeleton />;
 
  return (
    <View style={styles.container}>
      <Image source={{ uri: user.avatar }} style={styles.avatar} />
      <Text style={styles.name}>{user.name}</Text>
      <Text style={styles.bio}>{user.bio}</Text>
      <ProfileStats followers={user.followers} following={user.following} posts={user.postCount} />
      <Button title="Edit Profile" onPress={() => {}} variant="secondary" />
    </View>
  );
}
 
function ProfileHeaderSkeleton() {
  return (
    <View style={styles.container}>
      <Skeleton width={80} height={80} borderRadius={40} />
      <Skeleton width="60%" height={20} />
      <Skeleton width="80%" height={16} />
    </View>
  );
}