Expo Migration Overview

Expo Migration Overview

Document ID: EXPO-OVERVIEW-001
Version: 1.0.0
Created: 2026-01-04
Status: ACTIVE
Parent Document: README.md

---

Executive Summary

This document provides a high-level overview of the migration strategy for converting the Milk Men iOS application from Swift/SwiftUI to Expo (React Native).

Migration Objective

Primary Goal: Achieve complete feature parity with the Swift iOS application while establishing a foundation for future Android and Web deployment.

Secondary Goals:
- Leverage JavaScript/TypeScript developer ecosystem
- Maintain or exceed Swift app performance and UX
- Preserve all existing Supabase backend infrastructure
- Enable parallel development without disrupting production

---

Why Migrate to Expo?

### 1. Platform Expansion Readiness
- Current State: iOS-only (Swift/SwiftUI)
- Future State: iOS (initial), Android, Web (architecture-ready)
- Benefit: Single codebase for multiple platforms reduces long-term maintenance

### 2. Developer Ecosystem Access
- Current State: Swift/iOS developer pool limited
- Future State: JavaScript/TypeScript talent pool significantly larger
- Benefit: Easier hiring, faster onboarding, broader community support

### 3. Rapid Iteration Capability
- Current State: Native iOS builds require Xcode, provisioning profiles, build times
- Future State: Expo managed workflow enables instant preview via Expo Go
- Benefit: Faster development cycles, easier QA testing

### 4. Cross-Platform UI Consistency
- Current State: iOS-specific design patterns
- Future State: Unified React Native components
- Benefit: Consistent UX across platforms when expanded

---

Migration Strategy: Parallel Development

Why Parallel Development?

1. Risk Mitigation: Swift app remains in production while Expo app is built and validated
2. Zero Downtime: Users unaffected during migration
3. Validation Time: Extended beta testing period before cutover
4. Rollback Safety: Can abort migration without losing production app

Parallel Development Workflow

┌─────────────────────────────────────────────────────────┐
│                  CURRENT STATE                          │
│                                                         │
│  Swift iOS App (Production)                            │
│       │                                                 │
│       ├─→ Supabase Backend (PostgreSQL + Auth + RLS)   │
│       │                                                 │
│       └─→ Users (Active)                               │
└─────────────────────────────────────────────────────────┘

           ↓ (Weeks 1-16: Building Expo App)

┌─────────────────────────────────────────────────────────┐
│              PARALLEL DEVELOPMENT                       │
│                                                         │
│  Swift iOS App (Production) ───┐                       │
│                                 │                       │
│                          Supabase Backend              │
│                                 │                       │
│  Expo App (Development) ────────┘                      │
│                                                         │
│  • Same database                                        │
│  • Same RLS policies                                    │
│  • Same Edge Functions                                  │
│  • No backend changes allowed                           │
└─────────────────────────────────────────────────────────┘

           ↓ (Weeks 16-18: Testing & Validation)

┌─────────────────────────────────────────────────────────┐
│                 BETA TESTING                            │
│                                                         │
│  Swift iOS App (Production) ─────┐                     │
│                                   │                     │
│                            Supabase Backend            │
│                                   │                     │
│  Expo App (TestFlight) ───────────┘                    │
│       │                                                 │
│       └─→ Beta Users (50+)                             │
└─────────────────────────────────────────────────────────┘

           ↓ (Weeks 18-20: Gradual Rollout)

┌─────────────────────────────────────────────────────────┐
│                  CUTOVER                                │
│                                                         │
│  Expo App (Production) ────────→ Supabase Backend      │
│       │                                                 │
│       └─→ All Users                                    │
│                                                         │
│  Swift App (Deprecated, 30-day support)                │
└─────────────────────────────────────────────────────────┘

Critical Constraint: Backend Frozen

Invariant: The Supabase backend (schema, RLS policies, Edge Functions) must remain unchanged during parallel development.

Rationale:
- Both Swift and Expo apps must work with the same backend
- Any backend change could break the production Swift app
- All schema changes must wait until after cutover

Implication:
- If Expo migration reveals backend issues, document them but do not fix in backend
- Implement workarounds in Expo app if needed
- Backlog backend improvements for post-migration

---

Scope: Complete Feature Parity

What "Complete Parity" Means

All 60+ screens from Swift app must be implemented in Expo:
- Dashboard (Personalized stats, quick actions, AI insights)
- Locations (List, Map, Detail, Form, Google Places Search)
- Routes (Planner, Saved Routes, Visit Checkin, Store Visits)
- Team (Sales Team, Leaderboard, Agent Analytics, Activity Feed)
- Settings (Profile, Organization, Team Management, Invites)
- ...and all other screens

All 31 services must be ported to TypeScript:
- AuthService, OrganizationService, LocationService, RouteService
- VisitService, PipelineService, AnalyticsService, ActivityService
- GooglePlacesService, InventoryService, OrderService, BlitzCampaignService
- ...and all other services

All 23+ models must be defined as TypeScript interfaces and WatermelonDB models:
- Organization, Location, Agent, StoreVisit, Route, Territory, Region
- Account, Order, InventoryItem, WasteItem, BlitzCampaign
- ...and all other models

What Is NOT in Scope (Initial Release)

1. Android deployment - Architecture will support, but not tested/released
2. Web deployment - Architecture will support, but not tested/released
3. New features - Parity first, enhancements later
4. Backend modifications - Supabase unchanged (frozen)
5. Swift app deprecation - Both apps coexist for 30 days post-cutover

---

Architecture Overview

Current Stack (Swift/iOS)

┌─────────────────────────────────────────────┐
│         PRESENTATION LAYER                  │
│  • SwiftUI (Declarative UI)                 │
│  • NavigationStack (Type-safe routing)      │
│  • @Observable (State management)           │
│  • Custom design system                     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│       BUSINESS LOGIC LAYER                  │
│  • 31 Services (@Observable classes)        │
│  • Async/await (Concurrency)                │
│  • MainActor (Thread safety)                │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│            DATA LAYER                       │
│  • 23+ Swift structs (Codable models)       │
│  • SwiftData (Local persistence)            │
│  • Supabase Swift SDK (Backend)             │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         PLATFORM LAYER                      │
│  • CoreLocation (GPS)                       │
│  • MapKit (Maps)                            │
│  • LocalAuthentication (Biometrics)         │
│  • UserNotifications                        │
│  • AVFoundation (Camera/QR)                 │
└─────────────────────────────────────────────┘

Target Stack (Expo/React Native)

┌─────────────────────────────────────────────┐
│         PRESENTATION LAYER                  │
│  • React Native (Declarative UI)            │
│  • React Navigation (Routing)               │
│  • Zustand (State management)               │
│  • Tailwind/NativeWind (Styling)            │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│       BUSINESS LOGIC LAYER                  │
│  • 31 Service classes (TypeScript)          │
│  • Async/await (JavaScript)                 │
│  • React hooks (Lifecycle)                  │
│  • Custom hooks (Feature logic)             │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│            DATA LAYER                       │
│  • 23+ TypeScript interfaces                │
│  • WatermelonDB (Local persistence)         │
│  • @supabase/supabase-js (Backend)          │
│  • AsyncStorage (Simple KV pairs)           │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         PLATFORM LAYER                      │
│  • expo-location (GPS)                      │
│  • react-native-maps (Maps)                 │
│  • expo-local-authentication (Biometrics)   │
│  • expo-notifications                       │
│  • expo-camera (Camera/QR)                  │
└─────────────────────────────────────────────┘

Key Architectural Decisions

---

Timeline & Milestones

### Total Duration
16-20 weeks (4-5 months) with 1 full-time developer

Phase Breakdown

Critical Milestones

1. Week 2: Expo project initialized, first screen renders
2. Week 4: Authentication working, user can sign in
3. Week 5: Offline storage working, data persists locally
4. Week 7: Location CRUD complete, Google Places search working
5. Week 9: Route planning functional, optimization working
6. Week 13: All screens implemented (60/60)
7. Week 16: All tests passing (>70
8. Week 18: Beta release on TestFlight
9. Week 20: Production cutover

---

Success Criteria

Feature Completeness (100

Performance (Must Meet or Exceed Swift)

Quality

Security

---

Risk Assessment

High-Impact Risks

1. Performance Below Swift
- Probability: Medium
- Impact: High (user churn)
- Mitigation: Early benchmarking, optimization sprints

2. Data Corruption in Offline Sync
- Probability: Low
- Impact: Critical (data loss)
- Mitigation: Extensive testing, backup sync to Supabase

3. Timeline Overrun
- Probability: High
- Impact: Medium (budget, resources)
- Mitigation: Buffer time, prioritize MVP features

4. User Rejection of UX Changes
- Probability: Medium
- Impact: Critical (adoption failure)
- Mitigation: Visual regression testing, beta feedback

Risk Monitoring

• Weekly performance benchmarks (starting Phase 4)
• Daily sync integrity tests (starting Phase 3)
• Bi-weekly user acceptance reviews (starting Phase 8)
• Continuous crash monitoring (all phases)

---

Stakeholder Communication Plan

### Weekly Status Updates
- Progress against checklist
- Blockers and risks
- Screenshots/demos of completed screens
- Timeline adjustments

### Milestone Reviews
- Demo of completed phase
- Validation against success criteria
- Go/no-go decision for next phase

### Beta Testing Feedback Loop
- TestFlight invites (Week 18)
- In-app feedback form
- Weekly bug triage
- User acceptance sign-off

---

Next Steps

1. Immediate: Review and approve this overview document
2. Week 1: Begin Phase 0 (Project Setup & Governance)
3. Week 1: Create Phase Zero documentation (Charter, Glossary, etc.)
4. Week 2: Initialize Expo project, configure EAS
5. Week 2: Begin Phase 1 (Core Infrastructure)

---

Approval

Status: DRAFT (Pending Approval)
Approved By: _Pending_
Approval Date: _Pending_

Once approved, this overview governs the migration strategy and serves as the reference for all stakeholders.

---

This document is governed by the Master Implementation Prompt (CLAUDE.md). All execution follows the principles of anticipation over prediction, commitment only when signals converge, and preservation of reversibility.