# Mobile App Analysis Optimization Guide

**Last Updated:** 2026-02-02

Guide to the optimized parallel processing version of the comprehensive mobile app screenshot analysis.

## Performance Improvements

The optimized version (`analyze-screenshots-comprehensive-parallel.py`) provides **5-10x faster processing** while maintaining the same quality:

### Key Optimizations

1. **Parallel Processing**: Processes 5-10 screens concurrently using `ThreadPoolExecutor`
2. **Reduced Delays**: Base delay reduced from 2.0s to 0.5s with smart rate limiting
3. **Exponential Backoff**: Automatic retry with exponential backoff on rate limits
4. **Better Error Handling**: Graceful handling of API errors with retries
5. **Maintains Quality**: All 5 analysis passes remain unchanged for comprehensive analysis

### Performance Comparison

| Metric | Original Script | Optimized Script | Improvement |
|--------|----------------|------------------|-------------|
| **Processing Time** | ~15-20 min for 90 screens | ~3-5 min for 90 screens | **5-10x faster** |
| **Base Delay** | 2.0s | 0.5s | 4x reduction |
| **Concurrency** | 1 screen at a time | 8 screens concurrently | 8x parallelization |
| **Rate Limit Handling** | Fixed delay | Exponential backoff | Better resilience |

## Usage

### Basic Usage

```bash
# Run all passes on all screens with default settings (8 concurrent workers)
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py

# Process only first 10 screens for testing
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --limit 10

# Resume from existing analysis
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --resume
```

### Advanced Options

```bash
# Increase concurrency (faster, but may hit rate limits)
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --concurrent 10

# Reduce delay further (faster, but riskier)
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --delay 0.3

# Run specific passes only
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --passes 2 3 4 5

# Conservative settings (slower but safer)
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --concurrent 5 --delay 1.0
```

### Command-Line Options

- `--limit N`: Process only first N screenshots (0 = all, default: 0)
- `--passes 1 2 3 4 5`: Which passes to run (default: all)
- `--model MODEL`: Gemini model to use (default: gemini-2.5-flash; env `GEMINI_VISION_MODEL`)
- `--delay SECONDS`: Base delay between requests (default: 0.5)
- `--concurrent N`: Number of concurrent screens to process (default: 8)
- `--resume`: Resume from existing comprehensive analysis

## How It Works

### Parallel Processing Architecture

1. **Task Preparation**: All screens are prepared with their context and prompts
2. **Thread Pool**: Uses `ThreadPoolExecutor` with configurable worker count
3. **Rate Limiting**: Thread-safe rate limiting ensures minimum delay between requests
4. **Error Handling**: Each screen processed independently with retry logic
5. **Progress Tracking**: Real-time progress updates as screens complete

### Rate Limiting Strategy

- **Base Delay**: Minimum delay between requests (default: 0.5s)
- **Exponential Backoff**: On rate limit errors (429), delays increase: 0.5s → 1s → 2s
- **Thread Safety**: Lock ensures only one request at a time checks/updates timing
- **Automatic Retry**: Up to 3 retries with exponential backoff

### Quality Preservation

All 5 analysis passes remain unchanged:

1. **Pass 1**: Basic screen identification
2. **Pass 2**: Deep screen understanding
3. **Pass 3**: Cross-screen relationships
4. **Pass 4**: User flow extraction
5. **Pass 5**: Benefits and value extraction

The parallel version processes multiple screens concurrently but maintains the same analysis depth and quality.

## Recommended Settings

### For Fast Processing (Default)

```bash
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py
```

- **Concurrent**: 8 workers
- **Delay**: 0.5s
- **Best for**: Most use cases, balances speed and reliability

### For Maximum Speed

```bash
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --concurrent 10 --delay 0.3
```

- **Concurrent**: 10 workers
- **Delay**: 0.3s
- **Best for**: When you need fastest processing and can handle occasional retries

### For Conservative Processing

```bash
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive-parallel.py --concurrent 5 --delay 1.0
```

- **Concurrent**: 5 workers
- **Delay**: 1.0s
- **Best for**: When rate limits are strict or you want maximum reliability

## Troubleshooting

### Rate Limit Errors

If you see rate limit errors (429), try:

1. **Reduce concurrency**: `--concurrent 5`
2. **Increase delay**: `--delay 1.0`
3. **Process in batches**: `--limit 30` (process 30 at a time)

### API Errors

The script automatically retries with exponential backoff. If errors persist:

1. Check API key is valid
2. Verify API quota/limits
3. Check network connectivity
4. Review error messages in output

### Performance Issues

If processing is slower than expected:

1. Check network speed
2. Verify API response times
3. Monitor system resources (CPU/memory)
4. Consider reducing concurrency if system is overloaded

## Comparison with Original Script

| Feature | Original | Optimized |
|---------|----------|-----------|
| **Speed** | Sequential (slow) | Parallel (fast) |
| **Concurrency** | 1 screen | 8 screens (configurable) |
| **Delay** | 2.0s fixed | 0.5s base with backoff |
| **Error Handling** | Basic | Advanced with retries |
| **Rate Limiting** | Fixed delay | Smart with exponential backoff |
| **Quality** | Full 5 passes | Full 5 passes (same) |
| **Resume Support** | Yes | Yes |
| **Progress Tracking** | Basic | Enhanced |

## When to Use Each Script

### Use Original Script (`analyze-screenshots-comprehensive.py`)

- When you need maximum reliability and don't mind slower processing
- When debugging analysis issues
- When API rate limits are very strict

### Use Optimized Script (`analyze-screenshots-comprehensive-parallel.py`)

- **Recommended for most use cases**
- When processing large numbers of screenshots
- When speed is important
- When you want to balance speed and reliability

## Output

Both scripts produce identical output format:

- `docs/data/mobile-app-screenshot-analysis-comprehensive.json` - Main analysis file
- `docs/data/mobile-app-comprehensive/[screen-id].json` - Individual screen analyses

The optimized version includes additional metadata:

```json
{
  "concurrent_workers": 8,
  "base_delay": 0.5,
  ...
}
```

## Best Practices

1. **Start Conservative**: Begin with default settings, then increase concurrency if stable
2. **Monitor Progress**: Watch for rate limit errors and adjust accordingly
3. **Use Resume**: Always use `--resume` when re-running to skip completed screens
4. **Process in Batches**: For very large sets, use `--limit` to process in batches
5. **Save Progress**: Script saves progress after each screen, safe to interrupt

## Related Documentation

- [Comprehensive Analysis Guide](mobile-app-comprehensive-analysis-guide.md) - Detailed guide to analysis passes
- [Mobile App Documentation](mobile-app-documentation.md) - Main mobile app documentation
- [Analysis Summary](mobile-app-analysis-summary.md) - Analysis results summary