1. Project Health & Discovery
Before initiating any code translation, you Must perform an exhaustive automated audit of the iOS codebase.
- Structure Discovery: Run
find . -maxdepth 3 -type dto inspect the project layout and determine target boundaries. - Dependency Inventory: Read
Podfile,Package.swift, orCartfileto identify third-party libraries and SDK integrations. - UI Framework Identification: Run grep scans to quantify UI paradigms:
bash grep -rn "import SwiftUI" . | wc -l grep -rn "import UIKit" . | wc -l
2. Automated Subsystem Heuristic Matrix
You Must scan the iOS codebase for the following indicators and map them to their required supplemental reference guides:
| Detected iOS Indicator / Code Pattern | Required Supplemental Reference Guide | Primary Android Technology |
|---|---|---|
import CoreData OR import SwiftData OR *.xcdatamodeld |
database-coredata-to-room.md | Jetpack Room, SQLite, KSP |
import CoreLocation OR NSLocation*UsageDescription |
location-fusedprovider.md | Google Play Fused Location Provider |
import StoreKit |
in-app-billing.md | Google Play Billing Library 8 |
import HealthKit OR HKHealthStore |
health-connect.md | Jetpack Health Connect |
import CoreBluetooth OR CBCentralManager |
bluetooth-ble.md | Android BLE GATT & Scanner |
import AVFoundation OR AVCaptureSession |
camera-camerax.md | Jetpack CameraX (PreviewView, ImageAnalysis) |
import UserNotifications OR APNs handlers |
push-notifications-fcm.md | NotificationManager & Firebase Cloud Messaging |
BGTaskScheduler OR BGAppRefreshTask |
background-tasks-workmanager.md | Android WorkManager (CoroutineWorker) |
UserDefaults OR @AppStorage |
preferences-datastore.md | Jetpack Preferences DataStore |
NavigationStack OR NavigationView OR NavigationLink |
navigation-compose.md | Navigation Compose with Type-Safe Routing |
withAnimation OR .animation( OR matchedGeometryEffect |
ui-animations.md | Jetpack Compose Animation APIs |
import XCTest |
testing-unit-and-compose.md | JUnit5, MockK, ComposeTestRule |
fastlane/Snapfile OR snapshot( |
screenshots-screengrab.md | Fastlane Screengrab, UI Automator |
3. Project Structure Mapping
| iOS Concept | Android Equivalent | Architectural Rule |
|---|---|---|
Xcode Project (.xcodeproj) |
Root Gradle Project | Root folder containing settings.gradle.kts and build.gradle.kts. |
| Xcode Target | Gradle Module | Discrete buildable unit (:app, :core:database, :feature:profile). |
| Schemes & Configurations | Build Types & Flavors | Debug/Release map to Build Types; custom environments map to Product Flavors. |
| Info.plist | AndroidManifest.xml | Package metadata, exported activities, and runtime permission declarations. |
| Assets.xcassets | res/ (Resources) | Vector drawables (res/drawable), app icons (res/mipmap), colors/strings (res/values). |
4. Deep Functional Extraction & Domain Grounding
Before generating any Android architecture, theme, or code, you Must deduce the application's actual functional domain from source code, data entities, and service integrations.
- Domain Grounding: Never rely on the app's title or package name alone to infer motifs or visual design. Analyze models and endpoints to determine whether the app is financial, healthcare, social, productivity, media, or e-commerce.
- Non-Obvious Logic Extraction: Inspect for:
- Background sync mechanisms, observers, and periodic refresh tasks.
- State recovery logic during process death (
scenePhase,willResignActive,didEnterBackground). - Implicit data cascading (e.g. Core Data relationships with cascade deletes).
- Auth token refreshes and interceptors.
- Edge cases and failure states (offline mode, network retry backoff, validation rules).
5. Migration Brief Specification (feature_specification.md)
Before writing any target code, the agent Must generate and persist a formal
Migration Brief at .migration/feature_specification.md.
# Migration Brief: [App Name]
## 1. Domain & Core Purpose
- **Inferred Domain**: [e.g. Personal Finance & Budgeting]
- **Primary Value Proposition**: [Brief description grounded in code analysis]
## 2. Source Feature Inventory & Technical Mappings
| Feature Name | Source Implementation (iOS) | Target Implementation (Android) | Data/Backend Access | Complexity |
| :--- | :--- | :--- | :--- | :--- |
| User Authentication | `AuthenticationServices`, Keychain | Credential Manager, DataStore + Tink | REST `/auth/login` | Medium |
| Expense Ledger | `CoreData` (`TransactionEntity`) | Jetpack Room (`TransactionEntity`, `Dao`) | Local SQLite | High |
| Real-Time Exchange | Combine `URLSession.dataTaskPublisher` | Kotlin Coroutines, Flow, Retrofit | WebSocket / SSE | Medium |
## 3. Navigation & Screen Topology
- **Top-Level Navigation**: [Bottom navigation with 3 tabs: Dashboard, Transactions, Settings]
- **Flow Depth & Arguments**: [Detail views using typed navigation routes implementing `@Serializable`]
## 4. Non-Obvious Logic & Lifecycle Nuances
- [Auto-lock timer when app transitions to background]
- [Local notification scheduling upon reaching monthly spending limit]
## 5. Unsupported Elements & Fallback Strategy
- [Document any closed-source SDKs, proprietary Apple APIs, or missing direct equivalents]
6. Unsupported Element & Graceful Degradation Protocol
When encountering iOS APIs or third-party dependencies with no direct Android
equivalent (e.g. proprietary Apple frameworks like CloudKit, Handoff, Apple
Sign-In, or closed-source .xcframework binaries):
- Do NOT Fail Silently: Never omit functionality without explicit documentation.
- Define a Clean Abstraction Boundary: Create a Kotlin interface in the domain layer that encapsulates the expected capability.
Provide a Typed Stub with Actionable Instructions: ```kotlin /** * STUB(migration): iOS used Apple CloudKit for automatic key-value sync. * Android does not provide a direct 1:1 CloudKit equivalent. * * RECOMMENDED ALTERNATIVES: * 1. Firebase Firestore / Cloud Storage for cross-platform cloud sync. * 2. Google Drive AppData folder for private user backup. * * ACTION REQUIRED: Implement this interface using your selected cloud sync provider. */ interface CloudSyncService { suspend fun syncUserData(userId: String): Result
} class CloudSyncServiceStub @Inject constructor() : CloudSyncService { override suspend fun syncUserData(userId: String): Result
{ // TODO(migration): Replace stub with production cloud sync provider. return Result.success(Unit) } } ``` Log in Walkthrough: Record the stubbed component in
.migration/migration_walkthrough.mdunder Manual Action Items Required.
Glossary
| iOS Concept | Android Equivalent | Definition |
|---|---|---|
| Xcode Project | Root Gradle Project | Root folder containing build scripts and module settings. |
| Xcode Target | Gradle Module | Discrete buildable unit (:app, :core, :feature). |
| SwiftUI View | @Composable Function | Declarative UI building block. |
| ObservableObject | ViewModel + StateFlow | Architecture state holder surviving configuration changes. |
| NavigationStack | NavHost + Compose Navigation | Backstack manager and destination router. |
| Core Data / SwiftData | Jetpack Room | Object-relational SQLite abstraction layer. |
| UserDefaults / @AppStorage | Preferences DataStore | Asynchronous key-value storage. |
| BGTaskScheduler | Jetpack WorkManager | Deferrable, guaranteed background task scheduler. |
| AVFoundation (Capture) | Jetpack CameraX | Camera lifecycle-aware abstraction layer. |
| CoreLocation | FusedLocationProviderClient | High-accuracy, battery-optimized location client. |