apps/mobile-app/CLAUDE.md

StudyFlash Mobile App - Claude Code Configuration

StudyFlash Mobile App - Claude Code Configuration

Project Overview

StudyFlash is an AI-powered flashcard and study app built with React Native and Expo. It helps users create, study, and manage flashcards with intelligent features like AI content generation, spaced repetition, and adaptive learning.

Repository: https://github.com/studyflash-ai/mobile-app.git

Tech Stack

  • Framework: React Native 0.76.9 with Expo 52
  • Language: TypeScript 5.7.2
  • Navigation: Expo Router with typed routes
  • Styling: NativeWind 4.0 (Tailwind CSS for React Native)
  • State Management: Legend State 3.0 + Zustand
  • Backend: Supabase (auth, database, storage)
  • Authentication: Google Sign-In, Apple Authentication
  • Payments: RevenueCat (React Native Purchases)
  • Analytics: PostHog with session replay
  • Error Tracking: Sentry
  • Rich Text: TipTap editor with Tentap
  • Animations: React Native Reanimated 3.16

App Variants & Bundle IDs

  • Development: com.studyflash.dev - "Studyflash (dev)"
  • Preview: com.studyflash.preview - "Studyflash (preview)"
  • Production: com.studyflash.ai - "Studyflash"

Development Commands

Start Development

pnpm start                   # Start with development client (APP_VARIANT=development)
npx expo start --dev-client  # Alternative start command

Platform-Specific

pnpm android                # Run on Android
pnpm ios                    # Run on iOS
pnpm web                    # Run on web

Testing & Quality

pnpm test                   # Run Jest tests with watch mode
pnpm lint                   # ESLint linting
pnpm check-types            # TypeScript type checking
pnpm format                 # Prettier formatting
pnpm format:check           # Check Prettier formatting

Database & Environment

pnpm update-database-types  # Generate Supabase types
pnpm set-secrets            # Pull EAS environment variables

EAS Build & Deployment

# Development builds
eas build --profile development
eas build --profile development-ios-simulator

# Preview builds
eas build --profile preview

# Production builds
eas build --profile production
eas build --profile production-preview

Project Structure

/
├── app/                                          # Expo Router pages and layouts
│   ├── onboarding/                              # Onboarding/auth flow
│   │   ├── _layout.tsx                          # Onboarding layout
│   │   ├── index.tsx                            # Onboarding entry screen
│   │   ├── steps.tsx                            # Onboarding steps
│   │   └── tutorial.tsx                         # Onboarding tutorial
│   ├── (tabs)/                                  # Tab navigation group
│   │   ├── library/                             # Library tab
│   │   │   ├── _layout.tsx                      # Library layout
│   │   │   ├── index.tsx                        # Library main screen
│   │   │   └── bin.tsx                          # Library bin/trash
│   │   ├── (profile)/                           # Profile tab group
│   │   │   ├── _layout.tsx                      # Profile group layout
│   │   │   ├── index.tsx                        # Profile main screen
│   │   │   ├── settings.tsx                     # App settings
│   │   │   ├── goals.tsx                        # Learning goals
│   │   │   └── feedback.tsx                     # Profile feedback screen
│   │   ├── _layout.tsx                          # Tabs layout
│   │   ├── create.tsx                           # Create new content screen
│   │   ├── feedback.tsx                         # Main feedback screen
│   │   └── index.tsx                            # Home/dashboard screen
│   ├── study/                                   # Study modes group
│   │   ├── _layout.tsx                          # Study layout
│   │   ├── index.tsx                            # Study main screen
│   │   ├── quiz.tsx                             # Quiz mode
│   │   ├── completed.tsx                        # Study completion
│   │   └── cram.tsx                             # Cram study mode (static)
│   ├── course/[courseId]/                       # Course detail screens (outside tabs)
│   │   ├── _layout.tsx                          # Course layout (index + deck routes)
│   │   ├── index.tsx                            # Course tabbed interface (overview, flashcards, quiz, ai-assistant)
│   │   └── deck/[deckId].tsx                    # Deck tabbed interface (flashcards, quiz, summary, ai-assistant)
│   ├── upgrade/                                 # Upgrade flow
│   │   ├── _layout.tsx                          # Upgrade layout
│   │   ├── index.tsx                            # Upgrade main screen
│   │   └── welcome-premium.tsx                  # Welcome to premium screen
│   ├── _layout.tsx                              # Root layout
│   ├── index.tsx                                # App root/entry screen
│   ├── modal.tsx                                # Modal screen
│   ├── +html.tsx                                # Custom HTML root (web)
│   └── +not-found.tsx                           # 404/not found screen
├── components/                                  # Reusable React components
│   ├── CourseOverviewContent.tsx                # Course overview tab content
│   ├── CourseFlashcardsContent.tsx              # Course flashcards tab content
│   ├── CourseQuizContent.tsx                    # Course quiz tab content
│   ├── CourseAiAssistantContent.tsx             # Course AI assistant tab content
│   ├── DeckFlashcardsContent.tsx                # Deck flashcards tab content
│   ├── DeckQuizContent.tsx                      # Deck quiz tab content
│   ├── DeckSummaryContent.tsx                   # Deck summary tab content
│   ├── DeckAiAssistantContent.tsx               # Deck AI assistant tab content
│   └── [other components...]                    # Other reusable components
├── store/                                       # Legend State stores
├── api/                                         # React Query hooks and API calls
├── utils/                                       # Utility functions and helpers
├── hooks/                                       # Custom React hooks
├── types/                                       # TypeScript type definitions
├── assets/                                      # Images, fonts, icons
├── theme/                                       # Theme configuration
├── i18n/                                        # Internationalization
└── constants/                                   # App constants

Route examples

  • Onboarding
    • /onboarding - Onboarding entry screen
    • /onboarding/steps - Onboarding steps
    • /onboarding/tutorial - Onboarding tutorial
  • Upgrade
    • /upgrade/welcome-premium - Welcome to premium screen
  • Tabs (with tab bar navigation)
    • /(tabs) - Home/dashboard screen
    • /(tabs)/library - Library main screen
    • /(tabs)/library/bin - Library bin/trash
    • /(tabs)/create - Create new content screen
    • /(tabs)/(profile) - Profile main screen
    • /(tabs)/(profile)/settings - App settings
    • /(tabs)/(profile)/goals - Learning goals
    • /(tabs)/(profile)/feedback - Profile-specific feedback screen
    • /(tabs)/feedback - Main feedback/help screen
  • Course Screens (outside tabs, no tab bar)
    • /course/[courseId] - Course tabbed interface (overview, flashcards, quiz, ai-assistant)
    • /course/[courseId]/deck/[deckId] - Deck tabbed interface (flashcards, quiz, summary, ai-assistant)

    Note: Individual tab routes like /course/[courseId]/overview don't exist as separate routes. All tab content is handled by the main course/deck index files using extracted content components.
  • Study Modes
    • /study - Study main screen
    • /study/quiz - Quiz mode
    • /study/completed - Study completion screen
    • /study/cram - Cram study mode (static route)
  • Other Routes
    • /modal - Modal screen
    • /+not-found - 404/Not found handler

Route Notes

Feedback Routes: The app has two feedback routes serving different purposes:

  • /(tabs)/feedback - Main feedback/help screen accessible from the tab bar
  • /(tabs)/(profile)/feedback - Profile-specific feedback nested within the profile section

Layout Hierarchy: Each major section has its own _layout.tsx for proper navigation structure and screen organization.

Key Features & Flows

  • Onboarding: Multi-step user setup with personalization
  • Deck Creation: AI-powered flashcard generation from various sources
  • Study Modes: Flashcard review, cram mode, quiz mode
  • AI Assistant: Chat-based help and content generation
  • Subscription: Premium features with RevenueCat
  • Workspaces: Organization and collaboration
  • Analytics: Learning progress and statistics

Important Files

  • app.config.ts - Expo configuration with variant support
  • eas.json - EAS Build configuration
  • package.json - Dependencies and npm scripts
  • tailwind.config.js - NativeWind/Tailwind CSS config
  • types/database.types.ts - Generated Supabase types
  • utils/supabase.ts - Supabase client configuration
  • utils/honoClient.ts - API client setup

Custom Packages

The app uses several custom StudyFlash packages:

  • @studyflash-ai/common - Shared utilities
  • @studyflash-ai/learning-service - Learning algorithms
  • @studyflash-ai/types - Shared type definitions

Development Notes

Git Repository

  • Main Branch: main
  • Use git status and git branch to check current branch and changes

Environment Setup

  • Uses Expo development client (not Expo Go)
  • Requires EAS CLI for builds and updates
  • Supports iOS simulator and physical devices
  • Android requires development build

Code Style

  • ESLint + Prettier configuration
  • TypeScript strict mode
  • Tailwind CSS classes via NativeWind
  • Component-based architecture with hooks

Debugging & Monitoring

  • Sentry: Error tracking and performance monitoring
  • PostHog: Analytics, feature flags, session replay
  • Expo Dev Tools: Development debugging
  • React Query Dev Tools: API state inspection