​

iOS App Overview

​

Architecture

​

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

// 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

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

​

State Management

​

Global State

// 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

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

​

Navigation Patterns

​

Tab-Based Navigation

• Home (Swiping)
• Messages
• Scholarships
• Profile

​

Modal Presentations

• Profile creation
• College details
• Settings
• Share sheets

​

Navigation Stack

NavigationStack {
    MessageListView()
        .navigationDestination(for: Conversation.self) { conversation in
            ChatDetailView(conversation: conversation)
        }
}

​

Network Layer

​

API Client Pattern

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

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

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

• 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
• Navigation Guide
• Debugging Guide
• Testing Strategies