digital-pilates/CLAUDE.md

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
• 总是先总结方案,等我确认之后,再进行实现