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

# 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

# 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

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)

# List available simulators
flutter emulators

# Launch iOS Simulator
open -a Simulator

# Run app in debug mode
flutter run -d ios

Development Build (Physical Device)

# 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)

# Build release version
flutter build ios --release

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

Xcode Configuration

1. Open iOS Project in Xcode

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

# Run Flutter tests
flutter test

Integration Tests

# 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
• Create new app with same Bundle ID
• Fill in app metadata

2. Build and Archive

# 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:

<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

   cd ios
   pod repo update
   pod install --repo-update
   

2. Xcode Build Errors

   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

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
   flutter doctor
   

Performance Optimization

For iOS release builds:

# 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

# 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

# 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