# Comprehensive Mobile App Analysis System Guide

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

Guide to the comprehensive multi-pass analysis system for Ordio mobile app screenshots.

## Overview

The comprehensive analysis system performs deep, multi-level analysis of mobile app screenshots across 5 passes:

1. **Pass 1: Basic Screen Analysis** - Screen identification, UI elements, basic functionality
2. **Pass 2: Deep Screen Understanding** - Context, user goals, business value, state, interactions, edge cases
3. **Pass 3: Cross-Screen Relationships** - How screens connect, data flow, navigation patterns
4. **Pass 4: User Flow Extraction** - Complete user journeys, error recovery, flow variations
5. **Pass 5: Benefits and Value Extraction** - User benefits, value propositions, use cases

## Scripts

### Main Analysis Script

**`analyze-screenshots-comprehensive.py`** - Orchestrates all 5 analysis passes

**Usage:**
```bash
# Run all passes on all screens
GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive.py

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

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

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

**Options:**
- `--limit N` - Process only first N screenshots
- `--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` - Delay between requests (default: 2.0)
- `--resume` - Resume from existing comprehensive analysis

### Supporting Analysis Scripts

**`analyze-screen-relationships.py`** - Maps how screens connect and depend on each other
```bash
python3 v2/scripts/mobile-app/analyze-screen-relationships.py
```

**`extract-user-flows.py`** - Extracts complete user journeys and flow paths
```bash
python3 v2/scripts/mobile-app/extract-user-flows.py
```

**`analyze-feature-relationships.py`** - Maps feature dependencies and data flow
```bash
python3 v2/scripts/mobile-app/analyze-feature-relationships.py
```

**`analyze-app-structure.py`** - Analyzes overall app structure and architecture
```bash
python3 v2/scripts/mobile-app/analyze-app-structure.py
```

**`integrate-helpdesk-content.py`** - Cross-references analysis with helpdesk documentation
```bash
python3 v2/scripts/mobile-app/integrate-helpdesk-content.py
```

**`extract-benefits.py`** - Extracts user benefits by type and feature
```bash
python3 v2/scripts/mobile-app/extract-benefits.py
```

**`extract-value-propositions.py`** - Extracts and refines value propositions
```bash
python3 v2/scripts/mobile-app/extract-value-propositions.py
```

### Validation Scripts

**`validate-comprehensive-analysis.py`** - Validates analysis completeness and accuracy
```bash
python3 v2/scripts/mobile-app/validate-comprehensive-analysis.py
```

**`validate-enhanced-documentation.py`** - Validates documentation completeness
```bash
python3 v2/scripts/mobile-app/validate-enhanced-documentation.py
```

## Data Files Generated

### Comprehensive Analysis Data

- **`docs/data/mobile-app-comprehensive/[screenshot_id].json`** - Individual comprehensive analyses
- **`docs/data/mobile-app-screenshot-analysis-comprehensive.json`** - Combined comprehensive analysis

### Derived Analysis Data

- **`docs/data/mobile-app-screen-relationships.json`** - Screen relationship mapping
- **`docs/data/mobile-app-user-flows-complete.json`** - Complete user journeys
- **`docs/data/mobile-app-feature-relationships-deep.json`** - Feature dependency mapping
- **`docs/data/mobile-app-structure-analysis.json`** - App structure analysis
- **`docs/data/mobile-app-helpdesk-integration.json`** - Helpdesk content integration
- **`docs/data/mobile-app-benefits-comprehensive.json`** - Comprehensive benefits
- **`docs/data/mobile-app-value-propositions.json`** - Value propositions

### Validation Reports

- **`docs/data/mobile-app-analysis-validation.json`** - Analysis validation report
- **`docs/data/mobile-app-documentation-validation.json`** - Documentation validation report

## Analysis Pass Details

### Pass 1: Basic Screen Analysis

Extracts fundamental screen information:
- Screen name and feature area
- UI elements list
- Visible functionality
- Navigation paths
- Data displayed
- User actions
- German UI labels
- One-line description

**Output:** Basic screen identification and categorization

### Pass 2: Deep Screen Understanding

Extracts deep contextual understanding:
- **Screen context:** When and why user sees this screen
- **User goal:** What user is trying to accomplish
- **Business value:** Why screen exists, what problem it solves
- **State information:** Data shown, editable fields, read-only fields, current state
- **Interactions:** Action → outcome → next state → error possibilities
- **Edge cases:** Different scenarios and edge cases
- **Benefits:** User benefits from this screen
- **Mental model:** How screen supports user understanding

**Output:** Deep understanding of screen purpose, context, and interactions

### Pass 3: Cross-Screen Relationships

Analyzes how screens connect:
- **Connects to:** Screens this connects to, triggers, data passed
- **Depends on:** Screens this depends on, required data
- **Data flow:** How data flows to/from this screen
- **Navigation patterns:** Types of navigation (linear, branching, modal, back)
- **Feature dependencies:** Feature areas this integrates with
- **Alternative paths:** Alternative ways to reach this screen

**Output:** Screen relationship mapping and navigation patterns

### Pass 4: User Flow Extraction

Extracts complete user journeys:
- **User journeys:** Complete journeys with steps, goals, happy paths
- **Error recovery flows:** How errors are handled and recovered from
- **Flow variations:** Variations based on user role, data state, etc.

**Output:** Complete user journey documentation

### Pass 5: Benefits and Value Extraction

Extracts benefits and value propositions:
- **User benefits:** By user type (employee, manager, HR/admin, general)
- **Business value:** Problems solved, value propositions, differentiators, impact
- **Use cases:** Real-world scenarios with user types and benefits
- **Value statements:** Marketing-ready value statements

**Output:** Comprehensive benefits and value propositions

## Workflow

### Initial Comprehensive Analysis

1. **Run comprehensive analysis** (all passes):
   ```bash
   GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive.py
   ```
   This will take significant time (5 passes × 90 screens = 450 API calls). Consider using `--limit` for testing.

2. **Run supporting analyses**:
   ```bash
   python3 v2/scripts/mobile-app/analyze-screen-relationships.py
   python3 v2/scripts/mobile-app/extract-user-flows.py
   python3 v2/scripts/mobile-app/analyze-feature-relationships.py
   python3 v2/scripts/mobile-app/analyze-app-structure.py
   python3 v2/scripts/mobile-app/integrate-helpdesk-content.py
   python3 v2/scripts/mobile-app/extract-benefits.py
   python3 v2/scripts/mobile-app/extract-value-propositions.py
   ```

3. **Validate analysis**:
   ```bash
   python3 v2/scripts/mobile-app/validate-comprehensive-analysis.py
   ```

### Incremental Updates

When new screenshots are added or analysis needs refreshing:

1. **Run specific passes** on new screens:
   ```bash
   GEMINI_API_KEY=your-key python3 v2/scripts/mobile-app/analyze-screenshots-comprehensive.py --passes 1 2
   ```

2. **Re-run supporting analyses** to incorporate new data:
   ```bash
   python3 v2/scripts/mobile-app/extract-user-flows.py
   python3 v2/scripts/mobile-app/extract-benefits.py
   ```

## Cost and Time Considerations

**API Calls Required:**
- Full analysis: 5 passes × 90 screens = 450 API calls
- Per-pass analysis: 90 API calls per pass
- Testing (5 screens): 5 passes × 5 screens = 25 API calls

**Estimated Time:**
- Full analysis: ~2-3 hours (with 2s delay between requests)
- Per-pass analysis: ~30-45 minutes
- Testing (5 screens): ~5-10 minutes

**Cost:** Depends on Gemini API pricing. Check current rates at https://ai.google.dev/pricing

## Best Practices

1. **Start Small:** Test with `--limit 5` before running full analysis
2. **Use Resume:** Use `--resume` flag to continue interrupted analyses
3. **Incremental Updates:** Run specific passes when only certain aspects need updating
4. **Validate Regularly:** Run validation scripts after analysis updates
5. **Monitor API Usage:** Track API calls and costs
6. **Review Sample Output:** Manually review sample analyses for quality

## Integration with Documentation

The comprehensive analysis data is used to enhance:

- `mobile-app-documentation.md` - Main feature documentation
- `mobile-app-navigation.md` - Navigation flows
- `mobile-app-feature-relationships.md` - Feature relationships (to be created)
- `mobile-app-benefits.md` - Benefits documentation (to be enhanced)
- `mobile-app-user-flows.md` - User journey documentation (to be created)

## Related Documentation

- [mobile-app-documentation.md](mobile-app-documentation.md) - Main mobile app documentation
- [mobile-app-analysis-summary.md](mobile-app-analysis-summary.md) - Analysis summary
- [mobile-app-screens.md](mobile-app-screens.md) - Screen-by-screen reference