Qaptain

Create. Quiz. Track.

• Qaptain is a SwiftUI iOS app for managing classroom quizzes.
• Teachers can create classrooms, build multiple-choice quizzes, and monitor student progress in real-time.
• Students join classrooms using secure passwords, take interactive quizzes, and track their performance instantly.

Overview

• Platform: iOS (SwiftUI)
• Language: Swift
• Architecture: ObservableObject state management with singleton controllers/providers
• Backend: Firebase Firestore
• Dependencies: Firebase (Core, Auth, Firestore)

App Demos

• App Working (3 minutes)

  Qaptain-Demo.mp4

• Authentication & Onboarding (< 1 minute)

  Splash screen appears on launch, followed by login and onboarding

  auth-demo.mp4

Features

• Authentication

  • Email/password sign up and sign in via Firebase Auth
  • Forgot password flow with email reset
  • Reactive UI bound to authentication state

• Classrooms

  • Two roles: Teacher (creator) and Student (member)
  • Teachers can create classrooms (with auto-generated passwords)
  • Validate classroom name uniqueness per teacher (a teacher cannot create two classrooms with the same name)
  • Students join classrooms using a password
  • Search classrooms by name, creator, and creation month/year
  • Sort classrooms by newest/oldest
  • Pull-to-refresh and pagination support

• Quizzes

  • Create quizzes with a name, deadline, and multiple questions
  • Validate quiz name uniqueness per classroom (each classroom cannot have duplicate quiz names)
  • View quizzes for a classroom, sorted by creation date or deadline
  • Take quizzes; attempts are stored in stats
  • Teachers can view aggregated quiz stats for all students

• Members & Management

  • View all classroom members
  • Teachers can remove members (with automatic cleanup of their quiz stats)
  • Regenerate classroom passwords

• Onboarding & Help

  • First-launch detection to show an Instructions screen
  • Instructions accessible from the Classrooms toolbar

User Experience & Design

• UX Details

  • Splash screen overlay
  • Loading, Retry, and Error states are clearly displayed for all CRUD and data-fetching operations
  • Validates input as you type and updates submit buttons accordingly
  • Searchable and refreshable (pull-to-refresh) lists with a sorting menu on the toolbar

• Accessibility

  • Uses accessibility labels and combines card content for coherent VoiceOver reading
  • Descriptive labels for toolbar and buttons

• Adaptive & Responsive Design

  • Automatically switches between light and dark mode for a consistent look
  • Responsive on all iPhone and iPad screens, in both portrait and landscape

Project Structure (Selected Files)

File	Description
QaptainApp.swift	App entry point; configures Firebase and wires up the auth environment object
ContentView.swift	Root view that switches between AuthenticatedView, AuthView, or a loading state based on AuthController
AuthController.swift	ObservableObject singleton managing Firebase Auth, UI states, and auth workflows
DataManager.swift	Firestore data layer singleton for users, classrooms, quizzes, and stats
ClassroomProvider.swift	Singleton ObservableObject that fetches, caches, and manages classroom data with pagination, filtering, and UI state updates
ClassroomsView.swift	Main navigation for classrooms with segmented control, search, sorting, refresh, and modals
NetworkMonitor.swift	Singleton ObservableObject that monitors real-time network connectivity and updates UI via published properties
NetworkAlertModifier.swift / View+Extension.swift	Custom ViewModifier and extension providing automatic network connectivity alerts across the app
InstructionsView.swift	Onboarding and help view detailing app features for teachers and students

Additional views/providers/models exist for classroom details, quiz creation, enrollment, and stats

Data Model (Firestore)

• Collections and Subcollections

  

• DataManager Responsibilities (DataManager.swift)

  • The DataManager.swift is a central Singleton class that strictly handles all direct communication with Firebase Firestore.

  • This architectural choice separates data persistence logic from the UI/view model layer (ClassroomProvider.swift) and ensures consistent data validation and cleaning across the application.

  • It primarily relies on Swift's modern async/await concurrency and uses completion handlers for asynchronous results.

    Core Functionalities by Data Entity

    Area	Functionality & Key Implementation Details
    Architectural Core	Singleton Pattern: Enforced with a private init() and static let shared.
    App Launch Management	Onboarding State: Manages the app's first-launch state by checking and setting flags in UserDefaults (hasLaunchedBefore) to control the display of onboarding instructions.
    User Management	Propagating Name Updates: The critical updateUserNameEverywhere function ensures that when a user changes their name, it is consistently updated across: their main users document, every members subcollection document, the createdByName field in their classrooms, and their name in all relevant stats documents.
    Classroom Creation	Uniqueness & Setup: Validates the classroom name for uniqueness per creator. Creates the main Classroom document, automatically generates a unique password (UUID), and adds the creator as the initial member (isCreator: true).
    Classroom Enrollment	Secure Joining: Searches for classrooms using the join password, verifies the user isn't already enrolled, fetches user profile data, and adds the student to the members subcollection.
    Quiz Management & Stats	Atomic Creation: Creates new quizzes after validating name uniqueness per classroom. Uses a Firestore Batch to write all quiz questions simultaneously, ensuring atomicity. Attempt Tracking: The submitStatsForQuiz method manages student progress, either creating a new QuizStat record or appending a new Attempt object to an existing list, and updates the lastAttemptDate.
    Cleanup & Deletion	Deep Deletion: The destructive functions (deleteClassroom, deleteQuiz, removeMember) automatically perform cascading cleanup. For example, removing a member triggers the deletion of all their QuizStat records. Deleting a classroom recursively deletes all its quizzes, quizQuestions, QuizStats, and members.
    Input Validation	Data Cleaning: Uses cleanName(withName:) to normalize user input (names, titles) by trimming whitespace, ensuring data integrity before persistence.

App Flow

1. QaptainApp.swift configures Firebase and listens for auth changes via AuthController.swift.
2. ContentView.swift displays a SplashScreen.swift overlay, then routes to AuthView.swift or AuthenticatedView.swift based on AuthState.
3. The app monitors network connectivity via NetworkMonitor.swift and displays alerts using the .networkAlert() modifier when internet connection is lost, ensuring users are informed before Firebase operations.
4. Classrooms are loaded and observed via ClassroomProvider.swift to provide real-time updates, pagination, and role-based filtering.
5. ClassroomsView.swift is the primary entry for authenticated users, with segmented control for Enrolled vs Teaching classes, search, sort, and actions to create/enroll.
6. InstructionsView.swift is shown on first launch and available from the toolbar.

Setup

1. Prerequisites

• Xcode 15 or later (modern SwiftUI APIs)
• No CocoaPods or Swift Package Manager setup required (Firebase SDKs are already integrated)
• Internet connection for Firebase Auth & Firestore

2. Firebase Configuration

• The repository already includes a fully configured GoogleService-Info.plist, so when you clone the repo, the app is immediately linked to Firebase

• You can simply Build & Run in Xcode to use the existing Firebase Auth and Firestore setup. (no extra configuration needed)

• If you’d like to connect your own Firebase project instead:

  • Create a new project in the Firebase Console
  • Add an iOS app and download your own GoogleService-Info.plist file
  • Replace the existing file in the Xcode project
  • Enable Email/Password Authentication and Cloud Firestore (Native mode)

  Note: The included Firebase configuration is provided for demo and testing purposes only. Do NOT use it for production

3. Run the App

1. Open the project in Xcode
2. Choose an iOS Simulator or connected device
3. Click Run (⌘ + R) - the app will launch and automatically connect to Firebase

Coding Conventions

• SwiftUI-first architecture with @State, @StateObject, and @EnvironmentObject
• Singletons for cross-cutting controllers (AuthController.swift, DataManager.swift)
• Clear logging for major actions and errors
• Input cleaning and validation for user data

Project Context

Qaptain was developed as the final project for the course MPCS 51032 Advanced iOS Application Development (Spring 2025) at the University of Chicago.

Author

Developed by: Abhyas Mall
Project: Qaptain
Contact: mallabhyas@gmail.com

License

Qaptain is under the MIT License