| 1 | # Project Architecture & Guidelines (Expo Router + React Native + NativeWind) |
| 2 | |
| 3 | ## 1. System Architecture |
| 4 | - **Platform**: Expo SDK 52+ with React Native 0.76+ (New Architecture enabled). |
| 5 | - **Navigation**: Expo Router v4 (file-based navigation with native stack transitions). |
| 6 | - **Styling**: NativeWind v4 (Tailwind CSS compile-time engine for React Native). |
| 7 | - **Server State & Networking**: TanStack Query v5 with optimistic UI updates and AsyncStorage / SecureStore persistence. |
| 8 | |
| 9 | ## 2. Directory & Route Organization |
| 10 | - `app/`: File-based navigation hierarchy: |
| 11 | - `_layout.tsx`: Root layout with `SafeAreaProvider`, `QueryClientProvider`, and theme context. |
| 12 | - `(tabs)/_layout.tsx`: Bottom tab navigator. |
| 13 | - `(auth)/`: Authentication flows (login, register, forgot-password). |
| 14 | - `modal.tsx`: Native modal presentation screens (`presentation: "modal"`). |
| 15 | - `components/`: UI components categorized into `primitives/` (buttons, inputs, cards) and `features/` (domain widgets). |
| 16 | - `lib/`: |
| 17 | - `api.ts`: Typed fetch client with automatic token refreshing. |
| 18 | - `storage.ts`: Encrypted storage wrapper using `expo-secure-store`. |
| 19 | - `hooks/`: Custom React hooks for hardware sensors, haptics, and permissions. |
| 20 | |
| 21 | ## 3. Native Gestures & Safe Areas |
| 22 | - Always wrap root screens with `SafeAreaView` from `react-native-safe-area-context` to prevent notch and home-bar collisions. |
| 23 | - Utilize `react-native-gesture-handler` and `react-native-reanimated` for 60/120fps native-thread animations. |
| 24 | - Apply subtle haptic feedback using `expo-haptics` on meaningful user interactions (toggles, deletions, confirmations). |
| 25 | |
| 26 | ## 4. Cross-Platform Styling with NativeWind |
| 27 | - Write utility class names with `className="..."` supported by NativeWind v4 Babel/Metro transformer. |
| 28 | - Avoid inline styles for dynamic themes; consume CSS variables mapped in `global.css`. |
| 29 | - Handle platform differences via `Platform.select()` or `Platform.OS === 'ios'` only when native API differences require divergence. |
| 30 | |
| 31 | ## 5. Performance & Offline State |
| 32 | - Use `FlashList` from Shopify instead of `FlatList` for high-throughput scrolling feeds. |
| 33 | - Cache server queries with TanStack Query and persist cache to device storage for offline-first responsiveness. |
| 34 | - Enforce strict TypeScript compilation with zero `any` types. |
| 35 | |
| 36 | ## 6. Testing Conventions |
| 37 | - Use Jest with `jest-expo` preset for unit tests; `@testing-library/react-native` for component behavior tests. |
| 38 | - Use Maestro or Detox for end-to-end flows that cross native boundaries (camera, biometrics, push notifications) — Jest alone can't exercise real native modules. |
| 39 | - Snapshot-test NativeWind className output sparingly; prefer behavioral assertions (`getByRole`, `getByText`) over snapshot diffs that rot on every style tweak. |
| 40 | - Test both iOS and Android via EAS Build preview channels before merging changes to native config (`app.json`, `expo-module.config.json`). |
| 41 | |
| 42 | ## 7. Git Workflow & PR Conventions |
| 43 | - Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the screen or feature, e.g. `feat(profile): add avatar upload`. |
| 44 | - Any PR touching native modules or `app.json` config must include an EAS preview build link for reviewer testing on-device. |
| 45 | - Run `bun run lint` and `tsc --noEmit` before requesting review; New Architecture crashes are often silent type errors. |
| 46 | - Tag releases with the Expo/EAS build number, not just the git SHA, so crash reports map back to the exact submitted binary. |