# CLAUDE.md Template - Mobile App (React Native/Expo)
# Place this file in the ROOT of your project folder

> For React Native + Expo mobile app development

---

## 🎯 Project Overview

**Project Name:** [Your Mobile App Name]
**Type:** Mobile App (iOS + Android)
**Framework:** React Native with Expo
**One-liner:** [What does this app do in one sentence?]

### Problem Being Solved
[Describe the core problem your users face]

### Target User
[Who is this for? Be specific]

### Success Looks Like
[What does a successful v1.0 look like?]

---

## 🛠️ Tech Stack

| Layer | Technology | Why |
|-------|------------|-----|
| Framework | Expo SDK 52+ | Managed workflow, OTA updates |
| Navigation | Expo Router | File-based routing |
| Styling | NativeWind (Tailwind) | Consistent styling |
| State | Zustand | Simple, performant |
| Backend | Supabase | Auth, database, real-time |
| Push | Expo Notifications | Cross-platform push |
| Storage | MMKV or AsyncStorage | Local persistence |

---

## 📁 Project Structure

```
/app                    # Expo Router screens
  /(tabs)               # Tab navigation screens
  /(auth)               # Auth flow screens
  /[id]                 # Dynamic routes
/components             # Reusable UI components
  /ui                   # Base components (Button, Input)
  /features             # Feature-specific components
/lib                    # Utilities and helpers
  /supabase             # Supabase client
  /api                  # API calls
/hooks                  # Custom React hooks
/stores                 # Zustand stores
/types                  # TypeScript types
/constants              # App constants, colors
/assets                 # Images, fonts
```

---

## ✅ Coding Conventions

### General
- Use TypeScript with strict mode
- Prefer functional components with hooks
- Keep components small and focused
- Use descriptive variable names

### React Native Specific
- Use `StyleSheet.create()` for styles (or NativeWind)
- Handle both iOS and Android differences with `Platform.OS`
- Use `SafeAreaView` for screen containers
- Always handle keyboard avoidance
- Test on both iOS and Android simulators

### Navigation
- Use Expo Router for file-based routing
- Keep route params typed
- Handle deep linking

### Performance
- Use `React.memo()` for expensive components
- Use `useMemo` and `useCallback` appropriately
- Lazy load heavy screens
- Optimize images (use `expo-image`)

### State Management
```typescript
// stores/userStore.ts
import { create } from 'zustand';

interface UserStore {
  user: User | null;
  setUser: (user: User) => void;
  logout: () => void;
}

export const useUserStore = create<UserStore>((set) => ({
  user: null,
  setUser: (user) => set({ user }),
  logout: () => set({ user: null }),
}));
```

---

## 🚫 Do NOT

- Do not use `console.log` in production (use proper logging)
- Do not store sensitive data in AsyncStorage unencrypted
- Do not skip platform-specific testing
- Do not ignore keyboard handling
- Do not use inline styles (use StyleSheet or NativeWind)
- Do not block the JS thread with heavy computations

---

## 📱 Platform Considerations

### iOS Specific
- Handle notch/Dynamic Island with SafeAreaView
- Use SF Symbols for icons when possible
- Support Dark Mode via `useColorScheme()`
- Handle haptic feedback

### Android Specific
- Handle back button with `BackHandler`
- Use Material Design patterns where appropriate
- Handle different screen densities
- Test on various Android versions (API 24+)

---

## 📋 Current Phase

**Current Focus:** [e.g., "MVP Development - Core Features"]

**What's Done:**
- [x] Project setup with Expo
- [x] Navigation structure
- [ ] Authentication flow
- [ ] Core feature 1

**What's Next:**
- [ ] Implement auth screens
- [ ] Build main feature
- [ ] Add push notifications

---

## 🔗 Key Files to Know

| File | Purpose |
|------|---------|
| `/app/_layout.tsx` | Root layout with providers |
| `/lib/supabase/client.ts` | Supabase initialization |
| `/stores/userStore.ts` | User state management |
| `/app.config.ts` | Expo configuration |
| `/docs/PRD.md` | Product requirements |

---

## 💬 How to Work With Me

**My Role:** I am the product owner and reviewer. I plan, you implement.

**Your Role:** You write code, test on simulators, and ask clarifying questions.

**Before Coding:**
- Clarify if this needs iOS/Android specific handling
- Check existing components before creating new ones
- Consider offline-first if relevant

**Communication Style:**
- Explain platform differences when relevant
- Flag performance concerns proactively
- Suggest native alternatives when appropriate

---

## 📚 Reference Documents

- [PRD](/docs/PRD.md) - Product Requirements
- [User Stories](/docs/user-stories.md) - User stories
- [Tasks](/docs/tasks.md) - Current tasks

---

*Last Updated: [Date]*