Mobile Architecture Basics

npx create-expo-app@latest MyApp --template default@sdk-57
cd MyApp
npm install

MyApp/
├── app/                    # Expo Router - routes only
├── src/
│   ├── shared/             # UI primitives, API client, config
│   ├── entities/           # domain models (User, Order)
│   └── features/           # product slices (auth, orders, settings)
├── app.config.ts
└── package.json

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

┌─────────────────────────────────────────┐
│  app/ + features/*/screens, components  │  ← presentation
├─────────────────────────────────────────┤
│  entities/ + features/*/model, hooks    │  ← domain
├─────────────────────────────────────────┤
│  shared/api, shared/storage, adapters   │  ← data / infra
└─────────────────────────────────────────┘
         dependency direction: ↓ inward

// src/features/orders/screens/OrdersScreen.tsx - presentation orchestrates
import { useOrders } from "../hooks/useOrders";
import { OrderList } from "../components/OrderList";
 
export function OrdersScreen() {
  const { orders, loading, error, refresh } = useOrders();
  return <OrderList orders={orders} loading={loading} error={error} onRefresh={refresh} />;
}

// app/(tabs)/orders/index.tsx - one line when possible
export { OrdersScreen as default } from "@/features/orders";

// src/features/orders/index.ts - public API for the feature
export { OrdersScreen } from "./screens/OrdersScreen";
export type { Order } from "./model/types";

src/
├── shared/
│   ├── ui/              # Button, Screen, TextField - design-system primitives
│   ├── api/             # createApiClient(), error types
│   ├── config/          # env readers (no secrets in source)
│   └── lib/             # formatCurrency, date helpers
└── features/
    └── checkout/
        ├── components/  # PaymentSummary - checkout-specific
        └── hooks/       # useCheckout - checkout workflow

// src/shared/ui/Button.tsx - primitive, no domain knowledge
import { Pressable, StyleSheet, Text, type PressableProps } from "react-native";
 
type ButtonProps = PressableProps & { label: string };
 
export function Button({ label, style, ...rest }: ButtonProps) {
  return (
    <Pressable style={[styles.base, style]} {...rest}>
      <Text style={styles.label}>{label}</Text>
    </Pressable>
  );
}
 
const styles = StyleSheet.create({
  base: { paddingVertical: 12, paddingHorizontal: 20, borderRadius: 10, backgroundColor: "#2563eb" },
  label: { fontSize: 16, fontWeight: "600", color: "#fff" },
});

// src/entities/order/model/types.ts
export type OrderStatus = "pending" | "shipped" | "delivered" | "cancelled";
 
export type Order = {
  id: string;
  title: string;
  totalCents: number;
  status: OrderStatus;
  placedAt: string;
};

// src/entities/order/lib/formatOrderTotal.ts
import type { Order } from "../model/types";
 
export function formatOrderTotal(order: Order): string {
  return new Intl.NumberFormat("en-US", {
    style: "currency",
    currency: "USD",
  }).format(order.totalCents / 100);
}

// src/features/orders/index.ts
export { OrdersScreen } from "./screens/OrdersScreen";
export { OrderRow } from "./components/OrderRow";
export { useOrders } from "./hooks/useOrders";
export type { OrdersFilter } from "./model/types";

// src/features/dashboard/screens/DashboardScreen.tsx - imports public API only
import { OrderRow } from "@/features/orders";
import type { Order } from "@/entities/order";

// src/shared/api/createApiClient.ts
type ApiClient = {
  get<T>(path: string): Promise<T>;
  post<T>(path: string, body: unknown): Promise<T>;
};
 
export function createApiClient(baseUrl: string): ApiClient {
  return {
    async get<T>(path: string) {
      const response = await fetch(`${baseUrl}${path}`);
      if (!response.ok) throw new Error(`GET ${path} failed: ${response.status}`);
      return response.json() as Promise<T>;
    },
    async post<T>(path: string, body: unknown) {
      const response = await fetch(`${baseUrl}${path}`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(body),
      });
      if (!response.ok) throw new Error(`POST ${path} failed: ${response.status}`);
      return response.json() as Promise<T>;
    },
  };
}

// src/features/orders/api/ordersApi.ts
import type { Order } from "@/entities/order";
import type { ApiClient } from "@/shared/api/createApiClient";
 
export function createOrdersApi(client: ApiClient) {
  return {
    list: () => client.get<Order[]>("/orders"),
    byId: (id: string) => client.get<Order>(`/orders/${id}`),
  };
}

// src/shared/config/env.ts
import Constants from "expo-constants";
 
type AppConfig = {
  apiBaseUrl: string;
  appVariant: "development" | "staging" | "production";
};
 
export function getAppConfig(): AppConfig {
  const extra = Constants.expoConfig?.extra as Partial<AppConfig> | undefined;
  return {
    apiBaseUrl: extra?.apiBaseUrl ?? "https://api.staging.example.com",
    appVariant: extra?.appVariant ?? "development",
  };
}

// app.config.ts (excerpt)
export default {
  extra: {
    apiBaseUrl: process.env.EXPO_PUBLIC_API_URL,
    appVariant: process.env.APP_VARIANT ?? "development",
  },
};

// src/features/cart/hooks/useCart.ts - cart owns its state
import { create } from "zustand";
 
type CartItem = { productId: string; qty: number };
 
type CartStore = {
  items: CartItem[];
  add: (item: CartItem) => void;
  clear: () => void;
};
 
export const useCart = create<CartStore>((set) => ({
  items: [],
  add: (item) => set((s) => ({ items: [...s.items, item] })),
  clear: () => set({ items: [] }),
}));

// app/(tabs)/catalog/[id].tsx - route orchestrates navigation + cart, not features importing features
import { useLocalSearchParams, router } from "expo-router";
import { ProductDetailScreen } from "@/features/catalog";
import { useCart } from "@/features/cart";
 
export default function ProductRoute() {
  const { id } = useLocalSearchParams<{ id: string }>();
  const add = useCart((s) => s.add);
 
  return (
    <ProductDetailScreen
      productId={id ?? ""}
      onAddToCart={(productId) => {
        add({ productId, qty: 1 });
        router.push("/(tabs)/cart");
      }}
    />
  );
}

// src/features/orders/hooks/useOrders.test.ts
import { renderHook, waitFor } from "@testing-library/react-native";
import { useOrders } from "./useOrders";
import type { Order } from "@/entities/order";
 
const mockOrders: Order[] = [
  { id: "1", title: "Widget", totalCents: 999, status: "pending", placedAt: "2026-01-01" },
];
 
jest.mock("../api/ordersApi", () => ({
  ordersApi: { list: jest.fn(() => Promise.resolve(mockOrders)) },
}));
 
it("loads orders on mount", async () => {
  const { result } = renderHook(() => useOrders());
  await waitFor(() => expect(result.current.loading).toBe(false));
  expect(result.current.orders).toHaveLength(1);
});

// src/entities/order/lib/formatOrderTotal.test.ts - pure, no renderer
import { formatOrderTotal } from "./formatOrderTotal";
 
it("formats cents as USD", () => {
  expect(
    formatOrderTotal({ id: "1", title: "A", totalCents: 2500, status: "pending", placedAt: "" })
  ).toBe("$25.00");
});

monorepo/
├── apps/
│   └── mobile/              # Expo app - imports @acme/orders
├── packages/
│   ├── orders/              # entity + API types shared with web admin
│   └── ui/                  # design system
└── pnpm-workspace.yaml

// apps/mobile/package.json
{
  "dependencies": {
    "@acme/orders": "workspace:*",
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

// packages/orders/src/index.ts
export type { Order, OrderStatus } from "./model/types";
export { formatOrderTotal } from "./lib/formatOrderTotal";