Apple Watch Companion App

Surflink includes a native Apple Watch + iOS companion app built with SwiftUI. The source lives in the apple/ directory.

Architecture

The app is structured as a multi-target Xcode project managed with XcodeGen:

apple/
├── project.yml               # XcodeGen project definition
├── Shared/                   # Swift package shared across all targets
│   ├── Package.swift
│   └── Sources/
│       ├── Models/           # Data models (Session, Student, Drill, etc.)
│       ├── Services/         # API client, auth service, connectivity
│       └── Extensions/       # Swift extensions
│
├── SurfLink/                 # iOS companion app
│   └── Sources/
│       ├── SurfLinkApp.swift # Entry point
│       ├── Views/            # Login, pairing, settings
│       └── Services/         # iOS-specific services
│
├── SurfLinkWatch/            # watchOS app
│   └── Sources/
│       ├── SurfLinkWatchApp.swift
│       ├── CoachViews/       # Coach watch interface
│       ├── StudentViews/     # Student watch interface
│       └── Components/       # Shared watch components
│
└── SurfLinkWidgets/          # WidgetKit complications
    └── Sources/
        ├── SurfLinkWidgets.swift
        └── Widgets/          # Individual complication types

Targets

Setup

Prerequisites

• Xcode 15+
• XcodeGen installed (brew install xcodegen)
• Apple Developer account with watchOS provisioning

Generate Project

cd apple
xcodegen generate
open SurfLink.xcodeproj

Features

iOS Companion

• Login -- Supabase authentication (email/password)
• Watch Pairing -- Transfers auth tokens to the watch via WatchConnectivity
• Settings -- Account management and watch sync status

Coach Watch App

• Session Overview -- Current session status with athlete count
• Quick Actions -- Start/stop session timer, send notifications
• Student List -- Roster overview with skill levels
• Conditions -- Current surf conditions at a glance

Student Watch App

• Drill Timer -- Countdown timer for assigned drills
• Session Status -- View current session info
• Achievement Alerts -- Haptic notifications for earned badges
• Quick Stats -- Recent ride scores and session count

WidgetKit Complications

• Next Lesson -- Upcoming lesson time and location
• Conditions -- Current wave height and wind
• Session Count -- Total sessions this week/month
• Streak -- Current session streak

Auth Flow

1. User logs in on the iOS companion app via Supabase Auth
2. Auth tokens are transferred to the watch via WCSession.transferUserInfo
3. The watch app stores tokens in the Keychain
4. API requests from the watch include the auth token for Supabase calls
5. Token refresh is handled by the shared AuthService

Push Notifications

The watch app registers for APNs push notifications and sends the device token to the push_tokens table. Notifications from the web platform (lesson reminders, achievements, messages) are delivered to the watch as standard push notifications with haptic feedback.