CoffeeAtHome/README_iOS.md

# Coffee at Home - iOS Development Guide

## Prerequisites

Your iOS developer will need:

- **macOS** (iOS development only works on Mac)
- **Xcode 15.0+** (latest stable version from Mac App Store)
- **Flutter SDK** (latest stable version)
- **CocoaPods** (dependency manager for iOS)
- **iOS Simulator** or physical iOS device for testing

## Setup Instructions

### 1. Install Flutter

```bash
# Download Flutter SDK from https://flutter.dev/docs/get-started/install/macos
# Or use Homebrew:
brew install --cask flutter

# Verify installation
flutter doctor
```

### 2. Install Xcode and iOS Tools

```bash
# Install Xcode from Mac App Store
# Accept Xcode license
sudo xcodebuild -license accept

# Install iOS Simulator
sudo xcode-select --install

# Install CocoaPods
sudo gem install cocoapods
```

### 3. Clone and Setup Project

```bash
git clone <your-repo-url>
cd CoffeeAtHomeFlutter

# Get Flutter dependencies
flutter pub get

# Install iOS dependencies
cd ios
pod install
cd ..
```

## Building for iOS

### Development Build (iOS Simulator)

```bash
# List available simulators
flutter emulators

# Launch iOS Simulator
open -a Simulator

# Run app in debug mode
flutter run -d ios
```

### Development Build (Physical Device)

```bash
# Connect iOS device via USB
# Ensure device is in Developer Mode (Settings > Privacy & Security > Developer Mode)

# List connected devices
flutter devices

# Run on connected device
flutter run -d <device-id>
```

### Release Build (App Store)

```bash
# Build release version
flutter build ios --release

# This creates: build/ios/archive/Runner.xcarchive
```

## Xcode Configuration

### 1. Open iOS Project in Xcode

```bash
open ios/Runner.xcworkspace
```

### 2. Configure App Settings

In Xcode, update these settings:

- **Bundle Identifier**: `com.yourcompany.coffeeatHome`
- **Display Name**: `Coffee at Home`
- **Version**: `1.0.0`
- **Build Number**: `1`
- **Deployment Target**: `iOS 12.0+`

### 3. Code Signing

- **Team**: Select your Apple Developer Team
- **Provisioning Profile**: Automatic (or select specific profile)
- **Signing Certificate**: Developer/Distribution certificate

### 4. App Icons and Launch Screen

- Replace icons in `ios/Runner/Assets.xcassets/AppIcon.appiconset/`
- Update launch screen in `ios/Runner/Base.lproj/LaunchScreen.storyboard`

## Testing

### Unit Tests

```bash
# Run Flutter tests
flutter test
```

### Integration Tests

```bash
# Run integration tests on iOS
flutter drive --target=test_driver/app.dart -d ios
```

## App Store Submission

### 1. Create App Store Connect Entry

- Go to [App Store Connect](https://appstoreconnect.apple.com)
- Create new app with same Bundle ID
- Fill in app metadata

### 2. Build and Archive

```bash
# Clean previous builds
flutter clean
flutter pub get

# Build for release
flutter build ios --release

# Open in Xcode for archiving
open ios/Runner.xcworkspace
```

In Xcode:
1. Select **Generic iOS Device** as destination
2. Go to **Product > Archive**
3. Once archived, click **Distribute App**
4. Choose **App Store Connect**
5. Upload to App Store Connect

### 3. Submit for Review

- Complete app metadata in App Store Connect
- Add screenshots (iPhone 6.7", 6.5", 5.5" and iPad Pro)
- Submit for App Store review

## Platform-Specific Features

### iOS-Specific Dependencies

The app uses these iOS-compatible packages:

- `shared_preferences` - Local storage
- `sqflite` - SQLite database
- `image_picker` - Camera/gallery access
- `go_router` - Navigation
- `provider` - State management

### Permissions

Add these to `ios/Runner/Info.plist` if needed:

```xml
<key>NSCameraUsageDescription</key>
<string>This app needs camera access to take photos of coffee.</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photo library access to select coffee images.</string>
```

## App Architecture

### Data Flow

```
CSV Files (Assets) → CsvDataService → StorageService → UI
User Data → SQLite → UserDataService → StorageService → UI
```

### Key Features Working on iOS

- ✅ **CSV Data Loading**: Coffee catalog from bundled CSV files
- ✅ **SQLite Storage**: User collections and journal entries
- ✅ **Material Design**: Consistent UI across platforms
- ✅ **Dark Theme**: Coffee-themed color scheme
- ✅ **Navigation**: Bottom navigation with go_router
- ✅ **State Management**: Provider pattern
- ✅ **Image Handling**: Coffee photos and gallery

## Troubleshooting

### Common Issues

1. **Pod Install Fails**
   ```bash
   cd ios
   pod repo update
   pod install --repo-update
   ```

2. **Xcode Build Errors**
   ```bash
   flutter clean
   flutter pub get
   cd ios && pod install
   ```

3. **Signing Issues**
   - Ensure Apple Developer account is active
   - Check Bundle ID matches App Store Connect
   - Verify certificates are valid

4. **Simulator Not Found**
   ```bash
   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
   flutter doctor
   ```

### Performance Optimization

For iOS release builds:

```bash
# Build with optimization
flutter build ios --release --split-debug-info=debug-symbols --obfuscate

# Reduce app size
flutter build ios --release --tree-shake-icons
```


### App Icon Requirements

- 1024x1024 PNG for App Store
- Various sizes generated automatically by Xcode

## Support

### Debug Information

```bash
# Get detailed device info
flutter doctor -v

# Check iOS specific setup
flutter doctor --verbose

# View logs during development
flutter logs
```

### Contact

For iOS-specific issues, the developer can:

1. Check Flutter iOS documentation: https://flutter.dev/docs/deployment/ios
2. Review Apple Developer guidelines: https://developer.apple.com/ios/
3. Contact the main development team with specific error messages

---

## Quick Start Commands

```bash
# Setup (one-time)
flutter pub get
cd ios && pod install && cd ..

# Development
flutter run -d ios

# Release Build
flutter build ios --release
open ios/Runner.xcworkspace
```