baijum/platform-parity-audit

Platform Parity Audit

Systematically compare the iOS port against the Android reference implementation to identify missing features, partial implementations, and behavioral differences. The audit has three layers that can be run independently.

Layer 1: Code-Level Structural Diff (no devices needed)

Compare source files between platforms to find functional gaps. This is the fastest layer and should always be run first.

Step 1: Inventory Android screens and ViewModels

List all Android UI files and ViewModels:

ls app/src/main/java/com/baijum/ukufretboard/ui/*.kt
ls app/src/main/java/com/baijum/ukufretboard/viewmodel/*.kt

Step 2: Inventory iOS screens and ViewModels

List all iOS View and ViewModel files:

ls iosApp/UkuleleCompanion/Views/*.swift
ls iosApp/UkuleleCompanion/ViewModels/*.swift

Step 3: Map Android screens to iOS counterparts

Build a feature matrix by matching each Android screen to its iOS equivalent. Use the mapping table below as a starting reference:

| Category | Android Screen (ui/) | iOS Screen (Views/) | |----------|---------------------|---------------------| | Play | FretboardScreen.kt (Explorer) | ExplorerView.swift | | Play | TunerTab.kt | TunerView.swift | | Play | PitchMonitorTab.kt | PitchMonitorView.swift | | Play | MetronomeTab.kt | MetronomeView.swift | | Play | ChordLibraryTab.kt | ChordLibraryView.swift | | Play | FavoritesTab.kt | FavoritesView.swift | | Create | SongbookTab.kt | SongbookView.swift | | Create | MelodyNotepadView.kt | MelodyNotepadView.swift | | Create | StrumPatternsTab.kt | StrumPatternsView.swift | | Create | ProgressionsTab.kt | ProgressionsView.swift | | Learn | TheoryLessonsView.kt | TheoryLessonsView.swift | | Learn | TheoryQuizView.kt | TheoryQuizView.swift | | Learn | IntervalTrainerView.kt | IntervalTrainerView.swift | | Learn | NoteQuizView.kt | NoteQuizView.swift | | Learn | ChordEarTrainingView.kt | ChordEarTrainingView.swift | | Learn | ScalePracticeView.kt | ScalePracticeView.swift | | Learn | LearningProgressView.kt | LearningProgressView.swift | | Learn | DailyChallengeView.kt | DailyChallengeView.swift | | Learn | PracticeRoutineView.kt | PracticeRoutineView.swift | | Learn | ChordTransitionView.kt | ChordTransitionsView.swift | | Learn | PlayAlongView.kt | PlayAlongView.swift | | Learn | AchievementsView.kt | AchievementsView.swift | | Reference | CapoGuideView.kt | CapoGuideView.swift | | Reference | CircleOfFifthsView.kt | CircleOfFifthsView.swift | | Reference | ChordSubstitutionsView.kt | ChordSubstitutionsView.swift | | Reference | ScaleChordView.kt | ScaleChordsView.swift | | Reference | FretboardNoteMapView.kt | FretboardNoteMapView.swift | | Reference | GlossaryView.kt | GlossaryView.swift | | Other | SettingsSheet.kt | SettingsView.swift | | Other | HelpView.kt | HelpView.swift | | Other | OnboardingScreen.kt | OnboardingView.swift |

Step 4: Compare ViewModel properties

For each ViewModel pair, compare the Android StateFlow/MutableState properties against iOS @Published properties. Look for:

• Properties present in Android but missing in iOS (missing features)
• Functions in Android ViewModel with no iOS equivalent
• Different default values or enum options

Example comparison approach:

# Extract Android ViewModel public API
rg "val |var |fun " app/src/main/java/com/baijum/ukufretboard/viewmodel/FretboardViewModel.kt | head -40

# Extract iOS ViewModel public API
rg "@Published|func " iosApp/UkuleleCompanion/ViewModels/FretboardViewModel.swift | head -40

Step 5: Compare Settings

Compare all settings keys between platforms:

# Android settings
rg "putBoolean\|putString\|putInt\|putFloat\|getBoolean\|getString\|getInt\|getFloat" app/src/main/java/com/baijum/ukufretboard/data/

# iOS settings
rg "UserDefaults\|@AppStorage\|defaults\." iosApp/UkuleleCompanion/ViewModels/SettingsViewModel.swift

Step 6: Compare sub-view features

For each matched screen pair, read both files and compare:

• Buttons and interactive elements
• Dialogs, sheets, and modals
• Toggle/switch options
• Picker/selector options
• Accessibility labels and hints

Step 7: Generate the feature matrix

Create a markdown table in docs/ios-parity-report.md with columns:

| Feature | Android File | iOS File | Status | Notes | |---------|-------------|----------|--------|-------|

Status values:

• matched — Feature exists and is functionally equivalent
• partial — Feature exists but is missing sub-features or has different behavior
• missing — Feature exists in Android but has no iOS counterpart
• ios-only — Feature exists in iOS but not Android

Layer 2: TOML-Based Feature Verification

The docs/videos/ directory contains TOML project files that document detailed feature scenarios. Use these as checklists.

Step 1: List all TOML projects

ls docs/videos/*/android.toml

Step 2: Parse each project file

For each android.toml, read the [[scene]] entries. Each scene has:

• name — what the scene demonstrates
• narration — description of the feature behavior
• recording_notes — step-by-step interaction instructions

Step 3: Verify each scene in iOS code

For each scene, search the iOS codebase for the described feature:

# Example: verify chord detection exists in iOS
rg "detect\|chord.*result\|ChordResult" iosApp/UkuleleCompanion/Views/ExplorerView.swift

Mark each scene as:

• verified — the feature described in the scene exists in iOS
• partial — some aspects of the scene's feature are missing
• missing — the feature is not implemented in iOS

Step 4: Supplement with Learn and Reference

The TOML files cover Play and Create features only. For Learn and Reference screens, manually verify by reading the iOS view files and comparing against the Android equivalents.

Layer 3: Visual Screenshot Comparison (requires running devices)

Capture side-by-side screenshots to catch visual/layout differences.

Prerequisites

• Android emulator running with app installed (see android-screenshot-capture)
• iOS simulator running with app installed (see ios-simulator-run)

Step 1: Create output directory

mkdir -p docs/parity-screenshots/{android,ios}

Step 2: Capture Android screenshots

ADB=~/Library/Android/sdk/platform-tools/adb

# Launch app
$ADB shell am start -n com.baijum.ukufretboard/.MainActivity
sleep 3

# For each screen: navigate, wait, capture
# Example: Explorer
$ADB exec-out screencap -p > docs/parity-screenshots/android/explorer.png

# Example: Chord Library (via drawer)
$ADB shell input tap 80 200  # hamburger menu
sleep 1
$ADB shell uiautomator dump /sdcard/ui.xml 2>/dev/null
$ADB shell cat /sdcard/ui.xml | tr '>' '\n' | grep 'text="Chords"'
# Tap found coordinates
$ADB shell input tap <x> <y>
sleep 2
$ADB exec-out screencap -p > docs/parity-screenshots/android/chord-library.png

Step 3: Capture iOS screenshots

# Get booted simulator UUID
SIM_UUID=$(xcrun simctl list devices booted -j | python3 -c "import sys,json; devs=json.load(sys.stdin)['devices']; print([d['udid'] for ds in devs.values() for d in ds if d['state']=='Booted'][0])")

# Launch app
xcrun simctl launch $SIM_UUID com.baijum.ukufretboard.ios
sleep 3

# Capture each screen (navigate via UI or deep links if available)
xcrun simctl io $SIM_UUID screenshot docs/parity-screenshots/ios/explorer.png

iOS navigation automation is limited compared to ADB. For screens requiring navigation:

• Use xcrun simctl status bar overrides for consistent appearance
• Navigate screens manually in the simulator and capture programmatically
• Consider adding SwiftUI test hooks for automated navigation in the future

Step 4: Compare screenshots

Review the paired screenshots (android/<name>.png vs ios/<name>.png) visually or present them side-by-side. Look for:

• Missing buttons, sections, or controls
• Different layout or ordering of elements
• Missing icons or visual indicators
• Accessibility overlay differences (test with VoiceOver/TalkBack enabled)

Naming convention

Use consistent names matching the feature:

• explorer.png, tuner.png, metronome.png, chord-library.png
• settings.png, onboarding.png
• {feature}-{subscreen}.png for sub-screens (e.g., progressions-practice.png)

Output: Parity Report

Generate docs/ios-parity-report.md containing:

1. Summary — overall parity percentage and key gaps
2. Feature matrix — full table from Layer 1
3. TOML verification results — scene-by-scene status from Layer 2
4. Screenshot pairs — references to captured images from Layer 3 (if run)
5. Priority list — missing/partial features ranked by importance

Quick Reference

| Task | Command | |------|---------| | List Android UI files | ls app/src/main/java/com/baijum/ukufretboard/ui/*.kt | | List iOS View files | ls iosApp/UkuleleCompanion/Views/*.swift | | List Android ViewModels | ls app/src/main/java/com/baijum/ukufretboard/viewmodel/*.kt | | List iOS ViewModels | ls iosApp/UkuleleCompanion/ViewModels/*.swift | | Compare ViewModel API | rg "val \|var \|fun " <android.kt> vs rg "@Published\|func " <ios.swift> | | List TOML projects | ls docs/videos/*/android.toml | | Android screenshot | adb exec-out screencap -p > file.png | | iOS screenshot | xcrun simctl io <UUID> screenshot file.png |

Troubleshooting

• Files don't match names in mapping table: File naming conventions differ between platforms. Use the mapping table in Step 3 as the authoritative reference and update it if files are renamed.
• ViewModel lives in unexpected location: iOS TunerViewModel is defined inline in Views/TunerView.swift, not in ViewModels/. Check both directories.
• Shared KMP code not considered: Features implemented in shared/src/commonMain/ are available to both platforms. When a feature appears "missing" from iOS, check if the shared module provides it.
• iOS navigation harder to automate: Unlike ADB's uiautomator and input tap, iOS simulator automation is limited to xcrun simctl which has no UI element discovery. For full automation, use XCUITest or navigate manually.