> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinfindu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS App Overview

> Architecture and development guide for the FindU iOS app

# iOS App Overview

The FindU iOS app is a native SwiftUI application that helps students discover their perfect college match through an intuitive swiping interface.

<Note>
  **Current Version**: 1.5+ (App Store)

  * Fixed profile creation issues
  * Fixed cross-account data contamination
  * Added DEBUG tools for development
</Note>

## Architecture

The app follows the MVVM (Model-View-ViewModel) pattern with feature-based organization:

### Project Structure

```
ios_app/
├── Features/              # Feature modules
│   ├── auth/             # Authentication flow
│   ├── profileCreation/  # Onboarding
│   ├── swiping/          # Card interface
│   ├── messages/         # Chat system
│   └── scholarships/     # Financial aid
├── Shared/               # Shared components
├── Services/             # API & data services
└── Utils/                # Utilities
```

### Architecture Principles

#### MVVM Pattern

```swift theme={null}
// Model
struct School: Identifiable {
    let id: String
    let name: String
    let matchScore: Double
}

// ViewModel
@MainActor
class SwipingViewModel: ObservableObject {
    @Published var schools: [School] = []
    @Published var isLoading = false
    
    func loadSchools() async {
        isLoading = true
        schools = await api.fetchRecommendations()
        isLoading = false
    }
}

// View
struct SwipingView: View {
    @StateObject private var viewModel = SwipingViewModel()
    
    var body: some View {
        // UI implementation
    }
}
```

## Key Features

### Authentication System

* **Providers**: Apple Sign In, Google Sign In, Email
* **State Management**: Managed through `AuthState` enum
* **Supabase Integration**: Handles user sessions
* **Deep Linking**: Support for magic links

### Profile Creation Flow

Multi-step onboarding that collects:

1. Basic Information
2. Academic Profile
3. Preferences
4. Location & Demographics

### Swiping Interface

* **Card Stack**: Tinder-style interface
* **Gestures**: Swipe, tap, and drag support
* **Real-time Learning**: Algorithm adapts to swipes
* **Match Details**: Expandable college information

### Messaging System

* **Real-time Chat**: WebSocket-based updates
* **AI Advisor**: Integrated college counselor
* **Rich Messages**: Support for links, images
* **Notifications**: Push notification support

## Data Flow

```mermaid theme={null}
graph TD
    A[User Action] --> B[View]
    B --> C[ViewModel]
    C --> D[API Service]
    D --> E[Supabase]
    E --> F[Response]
    F --> C
    C --> G[Published State]
    G --> B
```

## State Management

### Global State

Managed through singletons and environment objects:

```swift theme={null}
// Global student data
class GlobalStudentDataState: ObservableObject {
    static let shared = GlobalStudentDataState()
    @Published var studentInfo: StudentInfo?
    @Published var hasCompletedOnboarding: Bool
}

// Feed state management (v1.5+)
class FeedStateManager: ObservableObject {
    static let shared = FeedStateManager()
    @Published var likedSchoolIds: [String] = []
    @Published var dislikedSchoolIds: [String] = []
    
    func resetCompletely() {
        // Clear all persisted data on logout
        likedSchoolIds = []
        dislikedSchoolIds = []
        clearAllPersistedData()
    }
}

// App state manager
class AppStateManager {
    func reset() {
        // Clear feed state to prevent cross-account contamination
        FeedStateManager.shared.resetCompletely()
    }
}
```

### Local State

Component-specific state using `@State` and `@StateObject`:

```swift theme={null}
struct CollegeDetailView: View {
    @State private var isExpanded = false
    @State private var selectedTab = 0
    
    var body: some View {
        // View implementation
    }
}
```

## Navigation Patterns

### Tab-Based Navigation

Main app navigation uses tabs:

* Home (Swiping)
* Messages
* Scholarships
* Profile

### Modal Presentations

Used for:

* Profile creation
* College details
* Settings
* Share sheets

### Navigation Stack

Deep navigation within features:

```swift theme={null}
NavigationStack {
    MessageListView()
        .navigationDestination(for: Conversation.self) { conversation in
            ChatDetailView(conversation: conversation)
        }
}
```

## Network Layer

### API Client Pattern

```swift theme={null}
class MatchingAPIClient {
    static let shared = MatchingAPIClient()
    
    func fetchRecommendations(for studentId: String) async throws -> [School] {
        let response = try await supabase
            .rpc("get_recommendations", params: ["student_id": studentId])
            .execute()
        
        return try decoder.decode([School].self, from: response.data)
    }
}
```

### Error Handling

```swift theme={null}
enum APIError: LocalizedError {
    case networkError
    case decodingError
    case unauthorized
    
    var errorDescription: String? {
        switch self {
        case .networkError:
            return "Network connection error"
        case .decodingError:
            return "Data format error"
        case .unauthorized:
            return "Please log in again"
        }
    }
}
```

## UI Components

### Custom Components

* `SchoolCard`: Swipeable card view
* `MatchScoreView`: Visual match percentage
* `StatTag`: Information badges
* `MessageBubble`: Chat UI elements

### Design System

* **Colors**: Defined in Assets catalog
* **Typography**: Custom fonts (Plus Jakarta Sans)
* **Spacing**: Consistent padding system
* **Animations**: Spring-based transitions

## Performance Optimization

### Image Loading

* Lazy loading with AsyncImage
* Caching strategy
* Thumbnail optimization

### Data Management

* Pagination for large lists
* Incremental loading
* Background refresh

### Memory Management

* Proper use of weak references
* View recycling in lists
* Image cache limits

## Development & Testing

### Manual Testing Approach

We rely on thorough manual testing for the iOS app:

1. **Build frequently**: Command+B to catch errors early
2. **Test on real devices**: Simulators miss some issues
3. **Test different iOS versions**: 16.0 minimum support
4. **Check different screen sizes**: iPhone SE to Pro Max
5. **Test offline scenarios**: Network interruptions
6. **Verify deep links**: Test universal links

### Testing Checklist

Before submitting changes:

* [ ] No build warnings or errors
* [ ] Tested on physical device
* [ ] Checked memory usage in Instruments
* [ ] Verified no console errors
* [ ] Tested edge cases (empty states, errors)
* [ ] Screenshots look correct on all sizes

## Debugging

### Debug Helpers

* Console logging with emojis
* Network request inspection
* State change tracking
* Performance monitoring

### Common Issues

1. **Profile Creation (Fixed in v1.5)**
   * **Issue**: Response decoding mismatch (snake\_case vs camelCase)
   * **Fix**: Proper response handling for database fields
   * **Note**: Database returns `num_ap_classes`, code expects `numAPClass`

2. **Cross-Account Data Contamination (Fixed in v1.5)**
   * **Issue**: UserDefaults persists liked/disliked schools across accounts
   * **Solution**: Call `FeedStateManager.resetCompletely()` on logout
   * **Debug**: Use DEBUG clear button in SchoolsView header

3. **Build Errors (v1.5)**
   * **Preview Errors**: Wrap preview code with `#if DEBUG`
   * **Missing Sample Data**: Check SmartQuestion.sampleFinancial
   * **Return in ViewBuilder**: Remove explicit return statements

4. **Authentication**: Verify Supabase config

5. **Push Notifications**: Check entitlements

6. **Deep Links**: Verify URL schemes

## Next Steps

* [SwiftUI Patterns](/ios-app/swiftui-patterns)
* [Navigation Guide](/ios-app/navigation)
* [Debugging Guide](/ios-app/debugging)
* [Testing Strategies](/ios-app/testing)