123 lines
6.4 KiB
Markdown
123 lines
6.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
### Development
|
|
- **`npm run ios`** - Build and run on iOS Simulator (iOS-only deployment)
|
|
|
|
### Testing
|
|
- Automated testing is minimal; complex logic should include Jest + React Native Testing Library specs under `__tests__/` directories or alongside modules
|
|
|
|
## Architecture
|
|
|
|
### Core Stack
|
|
- **Framework**: React Native (Expo Prebuild/Ejected) with TypeScript
|
|
- **Navigation**: Expo Router with file-based routing in `app/` directory
|
|
- **State Management**: Redux Toolkit with domain-specific slices in `store/`
|
|
- **Styling**: Custom theme system with light/dark mode support
|
|
|
|
### Directory Structure
|
|
- **`app/`** - Expo Router screens; tab flows in `app/(tabs)/`, feature-specific pages in nested directories
|
|
- **`store/`** - Redux slices organized by feature (user, nutrition, workout, etc.)
|
|
- **`services/`** - API services, backend integration, and data layer logic
|
|
- **`components/`** - Reusable UI components and domain-specific components
|
|
- **`hooks/`** - Custom React hooks including typed Redux hooks (`hooks/redux.ts`)
|
|
- **`utils/`** - Utility functions (health data, notifications, fasting, etc.)
|
|
- **`contexts/`** - React Context providers (ToastContext, MembershipModalContext)
|
|
- **`constants/`** - Route definitions (`Routes.ts`), colors, and app-wide constants
|
|
- **`types/`** - TypeScript type definitions
|
|
- **`assets/`** - Images, fonts, and media files
|
|
- **`ios/`** - iOS native code and configuration
|
|
|
|
### Navigation
|
|
- **File-based routing**: Pages defined by file structure in `app/`
|
|
- **Tab navigation**: Main tabs in `app/(tabs)/` (Explore, Coach, Statistics, Challenges, Personal, Fasting)
|
|
- **Route constants**: All route paths defined in `constants/Routes.ts`
|
|
- **Nested layouts**: Feature-specific layouts in nested directories (e.g., `app/nutrition/_layout.tsx`)
|
|
|
|
### State Management
|
|
- **Redux slices**: Feature-based state organization (17+ slices including user, nutrition, workout, mood, etc.)
|
|
- **Auto-sync middleware**: Listener middleware automatically syncs checkin data changes to backend
|
|
- **Typed hooks**: Use `useAppSelector` and `useAppDispatch` from `hooks/redux.ts` for type safety
|
|
- **Persistence**: AsyncStorage for local data persistence
|
|
|
|
### UI System
|
|
- **Themed components**: `ThemedText`, `ThemedView` with dynamic color scheme support
|
|
- **Custom icons**: `IconSymbol` component for iOS SF Symbols
|
|
- **UI library**: Reusable components in `components/ui/`
|
|
- **Colors**: Centralized in `constants/Colors.ts`
|
|
- **Safe areas**: `useSafeAreaTop` and `useSafeAreaWithPadding` hooks for device-safe layouts
|
|
|
|
### Data Layer
|
|
- **API client**: Centralized in `services/api.ts` with interceptors and error handling
|
|
- **Service modules**: Domain-specific services in `services/` (nutrition, workout, notifications, etc.)
|
|
- **Background tasks**: Managed by `backgroundTaskManager.ts` for sync operations
|
|
- **Local storage**: AsyncStorage for offline-first data persistence
|
|
|
|
### Native Integration
|
|
- **HealthKit**: Health data integration in `utils/health.ts` and `utils/healthKit.ts`
|
|
- **Apple Authentication**: Configured in Expo settings
|
|
- **Camera & Photos**: Food recognition and posture assessment features
|
|
- **Push Notifications**: `services/notifications.ts` with background task support
|
|
- **Haptic Feedback**: `utils/haptics.ts` for user interactions
|
|
- **Quick Actions**: Expo quick actions integration
|
|
|
|
### Context Providers
|
|
- **ToastContext** - Global toast notification system
|
|
- **MembershipModalContext** - VIP membership feature access control
|
|
|
|
## Key Architecture Patterns
|
|
|
|
- **Redux Auto-sync**: Listener middleware in `store/index.ts` automatically syncs checkin data changes to backend
|
|
- **Type-safe Navigation**: Expo Router with TypeScript for compile-time route safety
|
|
- **Authentication Flow**: `pushIfAuthedElseLogin` function handles auth-protected navigation
|
|
- **Theme System**: Dynamic theming with light/dark mode and color tokens
|
|
- **Service Layer**: Centralized API client with interceptors and error handling
|
|
- **Background Sync**: Automatic data synchronization via background task manager
|
|
|
|
## Development Conventions
|
|
|
|
### Import Patterns
|
|
- **Absolute imports**: Use `@/` prefix for all internal imports (e.g., `@/store`, `@/services/api`)
|
|
- **Alias configuration**: Defined in `tsconfig.json` paths
|
|
|
|
### Redux Patterns
|
|
- **Feature slices**: Each feature has its own slice (userSlice.ts, nutritionSlice.ts, etc.)
|
|
- **Typed hooks**: Always use `useAppSelector` and `useAppDispatch` from `hooks/redux.ts`
|
|
- **Async actions**: Use Redux Toolkit thunks for async operations
|
|
- **Auto-sync**: Listener middleware handles automatic data synchronization
|
|
|
|
### Naming Conventions
|
|
- **Components**: PascalCase (e.g., `ThemedText.tsx`, `FitnessRingsCard.tsx`)
|
|
- **Hooks**: camelCase with "use" prefix (e.g., `useAppSelector`, `useSafeAreaTop`)
|
|
- **Utilities**: camelCase (e.g., `health.ts`, `notificationHelpers.ts`)
|
|
- **Screen files**: kebab-case (e.g., `ai-posture-assessment.tsx`, `nutrition-label-analysis.tsx`)
|
|
- **Constants**: UPPER_SNAKE_CASE for values, PascalCase for types
|
|
|
|
### Code Style
|
|
- **ESLint**: Configured with `eslint-config-expo` in `eslint.config.js`
|
|
- **Formatting**: 2 spaces, trailing commas, single quotes (Prettier defaults)
|
|
- **TypeScript**: Strict mode enabled, use proper type annotations
|
|
|
|
### Navigation & Routing
|
|
- **Route constants**: Always use constants from `constants/Routes.ts` for navigation
|
|
- **Auth guards**: Implement using `useAuthGuard` hook for protected features
|
|
- **Typed routes**: Leverage Expo Router's TypeScript integration
|
|
|
|
### Testing Guidelines
|
|
- **Minimal automated tests**: Add Jest + React Native Testing Library for complex logic
|
|
- **HealthKit testing**: Requires real device; verify on iOS Simulator when possible
|
|
- **Integration tests**: Include reproduction steps and logs in PR descriptions
|
|
|
|
### iOS Development
|
|
- **Native changes**: Update `ios/` directory and re-run `npm run ios` after modifying Swift or entitlements
|
|
- **HealthKit**: Requires entitlements configuration; coordinate with release engineering
|
|
- **App signing**: Keep bundle IDs consistent with `app.json` and iOS project configuration
|
|
- **App Groups**: Required for widget and quick actions integration
|
|
|
|
### Git Workflow
|
|
- **Conventional Commits**: Use `feat`, `fix`, `chore` prefixes with optional scope
|
|
- **PR descriptions**: Include problem, solution, test evidence (screenshots, commands), iOS setup notes
|
|
- **Change grouping**: Group related changes; avoid bundling unrelated features |