Postan

A React Native app powered by Expo for AI-powered vacation media analysis that automatically detects themes, finds highlights, and generates engaging captions for your trips.

Features

• Trip Management: Create, save, and manage multiple trips with persistent storage
• Dashboard: View all your saved trips with statistics and quick access
• Media Import & Analysis: Select multiple photos/videos from device gallery
• AI-Powered Tagging: Uses Google Vision API to detect objects, locations, and activities
• Theme Detection & Clustering: Groups media by detected themes (beach, mountain, city, food, etc.)
• Highlight Selection: Scores photos using face detection, image quality, and other heuristics
• Caption Generation: Uses OpenAI API to generate Instagram-style captions with hashtags
• Narrative Generation: Creates engaging trip narratives based on analyzed media
• Prompt Generation: AI-powered prompt suggestions for social media posts
• Instagram Sharing: Share your analyzed media directly to Instagram
• Persistent Storage: Trips are saved locally using AsyncStorage and persist between app sessions
• Theme Support: Light and dark theme options with customizable color schemes
• Simple UI Flow: Clean, intuitive interface with progress indicators and results display

Prerequisites

• Node.js (v16 or higher) - Download
• Expo CLI - Install globally: npm install -g @expo/cli
• iOS Simulator (for iOS development on Mac) or Android Studio (for Android development)
• Google Cloud Platform account (for Vision API) - Sign up
• OpenAI account (for caption generation) - Sign up

Setup Instructions

1. Clone and Install Dependencies

# Navigate to the project directory
cd Postan

# Install all dependencies
npm install

2. Configure API Keys

The app uses environment variables for API keys. Create a .env file in the root directory:

# Create .env file in the root directory
touch .env

Add your API keys to the .env file:

GOOGLE_VISION_API_KEY=your_google_vision_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

Important Notes:

• The .env file is already in .gitignore and will not be committed to version control
• Do NOT commit your API keys to the repository
• The app will use mock data if API keys are not provided (useful for development)

Getting API Keys:

Google Vision API:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Cloud Vision API
4. Navigate to APIs & Services > Credentials
5. Click Create Credentials > API Key
6. Copy the API key and add it to your .env file
7. (Optional) Restrict the API key to Vision API only for security

OpenAI API:

1. Go to OpenAI Platform
2. Create an account or sign in
3. Navigate to API Keys section
4. Click Create new secret key
5. Copy the API key and add it to your .env file
6. Keep your API key secure and never share it publicly

3. Run the App

After setting up your .env file, start the development server:

# Start the Expo development server
npm start

# Or use the safe start script (handles errors gracefully)
npm run start-safe

Once the server starts, you can:

• Press i to open in iOS Simulator (Mac only)
• Press a to open in Android Emulator
• Press w to open in web browser
• Scan the QR code with Expo Go app on your physical device

Platform-specific commands:

# Run on iOS simulator (Mac only)
npm run ios

# Run on Android emulator
npm run android

# Run on web browser
npm run web

Project Structure

Postan/
├── App.js                          # Main app component with navigation
├── index.js                        # App entry point
├── app.json                        # Expo configuration
├── babel.config.js                 # Babel configuration with dotenv plugin
├── package.json                    # Dependencies and scripts
├── .env                            # Environment variables (create this file)
├── src/
│   ├── screens/
│   │   ├── HomeScreen.js           # Home screen with navigation
│   │   ├── DashboardScreen.js      # Trip dashboard and management
│   │   ├── SimpleTripScreen.js     # Trip creation and media selection
│   │   ├── TripDetailsScreen.js    # Individual trip details view
│   │   ├── AnalysisScreen.js       # Analysis progress screen
│   │   ├── ResultsScreen.js        # Results display screen
│   │   ├── NarrativeScreen.js      # Trip narrative and themes
│   │   └── PromptResultsScreen.js  # AI-generated prompt results
│   ├── services/
│   │   ├── ApiService.js           # External API integrations (Google Vision, OpenAI)
│   │   ├── AnalysisService.js      # Core analysis logic
│   │   ├── NarrativeService.js     # Narrative generation service
│   │   ├── PromptGenerationService.js  # Prompt generation service
│   │   ├── TripStorageService.js   # Trip persistence and management
│   │   └── InstagramShareService.js # Instagram sharing functionality
│   ├── context/
│   │   ├── AppContext.js           # Global app state management
│   │   └── ThemeContext.js         # Theme management (light/dark)
│   ├── components/
│   │   └── ErrorBoundary.js        # Error boundary component
│   ├── constants/
│   │   └── Colors.js               # Color constants and themes
│   └── utils/
│       ├── ColorSystemTest.js      # Color system testing utilities
│       └── ColorTestHelper.js      # Color testing helpers
├── assets/
│   ├── icon.png                    # App icon
│   └── splash.png                  # Splash screen image
└── README.md                       # This file

How It Works

1. Trip Creation

• Users create a new trip by selecting start and end dates
• Add photos/videos for each day of the trip
• Trip data is saved locally using AsyncStorage for persistence

2. Media Selection

• Users select photos/videos from their device gallery
• Supports multiple media items with preview thumbnails
• Shows file information and organizes media by date within the trip
• Uses Expo Image Picker and Media Library for cross-platform support

3. AI Analysis

• Each media item is analyzed using Google Vision API
• Detects objects, faces, landmarks, text, logos, and activities
• Categorizes content into themes (beach, mountain, city, food, etc.)
• Falls back to mock data if API keys are not configured

4. Theme Clustering

• Groups media by detected themes
• Identifies top 2-3 most common themes
• Sorts items within each theme by quality score

5. Highlight Selection

• Scores photos based on:
  • Presence of faces (especially happy faces)
  • High-confidence object detection
  • Landmark detection
  • Image quality metrics
• Selects top items per theme for highlights

6. Trip Storage

• Complete trip data is saved to AsyncStorage
• Includes all media, analysis results, and metadata
• Trips persist between app sessions
• Dashboard provides quick access to all saved trips

7. Caption & Narrative Generation

• Uses OpenAI GPT-3.5-turbo to generate captions
• Creates Instagram-style posts with relevant hashtags
• Generates engaging trip narratives based on analyzed themes
• Provides AI-powered prompt suggestions

8. Sharing

• Share analyzed media directly to Instagram
• Copy captions to clipboard
• Export functionality for sharing results

API Usage

Google Vision API

• Label Detection: Identifies objects and scenes
• Face Detection: Finds faces and emotions
• Landmark Detection: Recognizes famous locations
• Object Localization: Locates objects within images
• Text Detection: Extracts text from images
• Logo Detection: Identifies brand logos

OpenAI API

• Model: GPT-3.5-turbo
• Purpose: Generate engaging captions, narratives, and prompts
• Input: Detected themes, highlights, and media metadata
• Output: Instagram-style captions with hashtags, trip narratives, and social media prompts

Error Handling

• Graceful Fallbacks: Automatically uses mock data when APIs are unavailable
• User-Friendly Messages: Clear error messages for users
• Retry Mechanisms: Automatic retry for failed operations
• Loading States: Progress indicators show current processing step
• Error Boundary: Catches and displays React errors gracefully

Running Without Errors

Initial Setup Checklist

1. ✅ Install Node.js (v16+)
2. ✅ Install dependencies: npm install
3. ✅ Create .env file in root directory
4. ✅ Add API keys to .env file (or use mock data mode)
5. ✅ Install Expo CLI: npm install -g @expo/cli
6. ✅ Start Metro bundler: npm start

Common Setup Issues and Solutions

Issue: "Module not found" errors

# Solution: Clear cache and reinstall
rm -rf node_modules
npm install
expo start -c

Issue: "API key not defined" warnings

• This is normal if you haven't set up API keys
• The app will use mock data automatically
• To use real APIs, create .env file with your keys

**Issue: "Cannot find module '@env'"

• Ensure babel.config.js includes the dotenv plugin (already configured)
• Restart the Metro bundler: npm start or expo start -c

Issue: Permission errors on device

• Grant camera roll permissions when prompted
• For Android: Check app permissions in device settings
• For iOS: Check Privacy settings in device Settings app

Issue: "Expo CLI not found"

# Install Expo CLI globally
npm install -g @expo/cli

Issue: Metro bundler won't start

# Clear all caches
npm start -- --clear
# Or
expo start -c

Issue: Android/iOS build errors

# Clear and reinstall
rm -rf node_modules
npm install
npm start -- --clear

Development Mode (Without API Keys)

The app works in mock data mode if API keys are not configured:

• All analysis uses simulated data
• Perfect for development and testing
• No API costs incurred
• Full app functionality available

To use mock data mode:

1. Simply don't create a .env file, OR
2. Create .env but leave keys empty (app will detect and use mocks)

Troubleshooting

Common Issues:

1. API Key Errors

   • Ensure .env file exists in root directory
   • Check that keys are correctly named: GOOGLE_VISION_API_KEY and OPENAI_API_KEY
   • Verify no extra spaces or quotes around keys
   • Restart Metro bundler after changing .env

2. Permission Denied

   • Grant camera roll permissions when prompted
   • Check device settings for app permissions
   • On Android: Ensure READ_MEDIA_IMAGES and READ_MEDIA_VIDEO permissions are granted

3. Network Errors

   • Check internet connection
   • Verify API quotas and billing status
   • Check API key restrictions in Google Cloud Console
   • Ensure OpenAI account has available credits

4. Build Errors

   • Clear node_modules: rm -rf node_modules && npm install
   • Clear Expo cache: expo start -c
   • Update Expo CLI: npm install -g @expo/cli@latest
   • Check Node.js version: node --version (should be v16+)

5. Metro Bundler Issues

   • Stop the current process (Ctrl+C)
   • Clear cache: npm start -- --clear
   • Restart: npm start

Debug Mode:

• Check console logs for detailed error information
• Mock data is used automatically when APIs fail
• Progress indicators show current processing step
• Error boundary catches and displays React errors
• Use React Native Debugger or Chrome DevTools for debugging

Development Notes

• Uses AsyncStorage for persistent trip data
• Mock data available for offline development
• Responsive design for various screen sizes
• Material Design components (React Native Paper) for consistent UI
• Theme support with light and dark modes
• Error boundaries for graceful error handling
• Cross-platform support (iOS, Android, Web)

Limitations

• Video processing is minimal (metadata extraction only)
• Requires internet connection for AI analysis (unless using mock data)
• Free-tier API limits apply for Google Vision and OpenAI
• Large media files may take longer to process

Future Enhancements

• Enhanced video content analysis
• Offline analysis capabilities
• More sophisticated scoring algorithms
• Additional social media platform integrations
• Batch processing optimization
• Custom theme definitions
• Advanced filtering and search
• Cloud backup and sync

Additional Resources

• Expo Documentation
• React Native Documentation
• Google Vision API Docs
• OpenAI API Docs

License

This project is for demonstration purposes. Please ensure you comply with all API terms of service and usage limits.

---

Note: Remember to never commit your .env file or API keys to version control. The .env file is already included in .gitignore for your safety.