# Quick Start Guide

## Prerequisites Checklist

- [ ] Node.js 20+ installed
- [ ] npm 10+ installed
- [ ] Expo CLI: `npm install -g expo-cli`
- [ ] EAS CLI: `npm install -g eas-cli` (for builds)
- [ ] Git installed
- [ ] iOS Simulator (Mac) or Android Studio for mobile testing
- [ ] VS Code recommended with extensions:
  - Expo Tools
  - TypeScript Hero
  - React Native Tools
  - Prettier

---

## 1. Clone & Install

```bash
# Clone repository
git clone <repository-url>
cd carry-your-live

# Install dependencies
cd carry-your-live
npm install

# Verify installation
npx expo-doctor
```

---

## 2. Environment Setup

Create `.env` file in project root:

```bash
# API Configuration
EXPO_PUBLIC_API_URL=http://localhost:3000/api

# Optional: Analytics, crash reporting
EXPO_PUBLIC_SENTRY_DSN=
EXPO_PUBLIC_AMPLITUDE_KEY=
```

---

## 3. Run Development Server

### Terminal 1: Start Metro Bundler
```bash
npx expo start
```

### Terminal 2: Run on Platform
```bash
# iOS Simulator (Mac only)
npx expo start --ios

# Android Emulator
npx expo start --android

# Web Browser
npx expo start --web

# Physical device (scan QR code with Expo Go)
npx expo start --tunnel
```

---

## 4. Project Structure Quick Reference

```
carry-your-live/
├── app/                    # Expo Router screens
│   ├── _layout.tsx         # Root layout + providers
│   ├── (tabs)/             # Tab screens
│   │   ├── index.tsx       # Tasks list
│   │   ├── calendar.tsx    # Calendar view
│   │   └── settings.tsx    # Settings
│   └── add-task.tsx        # Add/edit task modal
├── src/
│   ├── components/         # Reusable UI
│   ├── database/           # WatermelonDB setup
│   ├── hooks/              # React hooks
│   ├── models/             # Database models
│   ├── constants/          # Config values
│   └── types/              # TypeScript types
```

---

## 5. Key Commands

```bash
# Development
npx expo start              # Start dev server
npx expo start -c           # Clear cache & start
npx expo start --ios        # iOS simulator
npx expo start --android    # Android emulator
npx expo start --web        # Web browser

# Code Quality
npx tsc --noEmit            # Type check
npx expo lint               # Lint
npm run format              # Format with Prettier

# Database
npx expo run:ios            # Build & run native iOS
npx expo run:android        # Build & run native Android

# Build
eas build --platform ios    # iOS build
eas build --platform android # Android build
eas build --platform web    # Web build

# Database inspection (development)
# Open in browser: chrome://inspect/#devices
# Or use React Native Debugger
```

---

## 6. Common Development Tasks

### Add a New Screen

1. Create file in `app/` (e.g., `app/profile.tsx`)
2. Export default component
3. Add to navigation in `app/(tabs)/_layout.tsx` or as modal in `app/_layout.tsx`

### Add a Database Field

1. Update schema in `src/database/schema.ts`
2. Update model in `src/models/`
3. Create migration in `src/database/migrations.ts`
4. Update forms/components to use new field

### Add a Category

Edit `src/constants/index.ts`:
```typescript
export const DEFAULT_CATEGORIES = [
  // ... existing
  { name: 'Travel', color: '#00BCD4', order: 6 },
];
```

### Modify Sync Logic

Edit `src/database/sync.ts`:
- `pullChanges()` - How to fetch from server
- `pushChanges()` - How to send to server
- Conflict resolution strategy

---

## 7. Debugging Tips

### Inspect Database
```typescript
// In any component
import { useDatabase } from '@/hooks/useDatabase';

const { database } = useDatabase();
// database.collections.get('tasks').query().fetch().then(console.log)
```

### Network Requests
- Use React Native Debugger
- Or flipper with `react-native-flipper`
- Enable `console.log` for sync operations

### TypeScript Errors
```bash
# Full type check
npx tsc --noEmit

# Check specific file
npx tsc --noEmit src/components/TaskItem.tsx
```

---

## 8. Testing Checklist

### Before Commit
- [ ] `npx tsc --noEmit` passes
- [ ] `npx expo lint` passes
- [ ] App runs on iOS simulator
- [ ] App runs on Android emulator
- [ ] App runs on web
- [ ] Offline mode works (disable network)
- [ ] Sync works (with mock server)

### Manual Testing Flow
1. **Add Task**: Open app → FAB → Fill form → Submit → Verify in list
2. **Category Filter**: Tap categories → Verify filtering
3. **Complete Task**: Tap checkbox → Verify strikethrough + move to completed
4. **Delete Task**: Swipe left → Confirm → Verify removal
5. **Subtasks**: Add task with subtasks → Verify rendering
6. **Calendar**: Navigate to calendar → Select date → Verify tasks
7. **Settings**: Toggle dark mode → Verify persistence
8. **Offline**: Airplane mode → Add/edit tasks → Re-enable → Verify sync

---

## 9. Troubleshooting

| Issue | Solution |
|-------|----------|
| `npx expo start` fails | `rm -rf node_modules && npm install` |
| Metro bundler issues | `npx expo start -c` |
| iOS build fails | `cd ios && pod install && cd ..` |
| Android build fails | `cd android && ./gradlew clean && cd ..` |
| TypeScript errors | Check `tsconfig.json` extends `expo/tsconfig.base` |
| Database not persisting | Verify `expo-sqlite` installed, check `DatabaseProvider` wraps app |
| Sync not working | Check API URL in `.env`, verify server running |
| Animations laggy | Enable `useNativeDriver: true` where possible |

---

## 10. Useful Resources

- [Expo Documentation](https://docs.expo.dev/)
- [WatermelonDB Docs](https://nozbe.github.io/WatermelonDB/)
- [React Hook Form](https://react-hook-form.com/)
- [Expo Router](https://expo.github.io/router/)
- [Reanimated 3](https://docs.swmansion.com/react-native-reanimated/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

---

## 11. Project Scripts (package.json)

```json
{
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web",
    "lint": "expo lint",
    "typecheck": "tsc --noEmit",
    "format": "prettier --write \"**/*.{ts,tsx,json,md}\"",
    "db:studio": "npx expo run:ios --configuration Debug",
    "build:ios": "eas build --platform ios",
    "build:android": "eas build --platform android",
    "build:web": "eas build --platform web",
    "submit:ios": "eas submit --platform ios",
    "submit:android": "eas submit --platform android"
  }
}
```