TripDataHub

1Overview

What it is · why it exists · who it's for · core features

What it is

TripDataHub is an iOS app (formerly "BidProSchedule"; bundle ID still com.sfune.BidProSchedule) that gives airline/cargo pilots a timezone-aware view of their crew duty schedule. The pilot exports a schedule PDF from CrewAccess, shares it into the app via the iOS Share Sheet, and the app parses, stores, and renders it as a duty chronology (Timeline) and an 8-week Bid Period calendar grid (iPad).

Why it exists

CrewAccess presents schedules as PDFs with raw UTC and local times mixed together — no easy chronological "what do my next two weeks look like" view, no countdown to the next flight, no way to see a colleague's schedule. TripDataHub turns that PDF into:

• A single, timezone-correct duty chronology (Timeline) you can read at a glance.
• A Bid Period calendar grid (iPad) showing the whole period at once, with manually tracked reserve / call-out / personal commitments alongside assigned trips.
• A countdown to the next flight (widget + Live Activity), so you don't have to mentally track time-to-report.
• Optional read-only schedule sharing with mutually-approved colleagues.

Target users

• Cargo/airline pilots who use CrewAccess (positioned in the App Store as "brown-tail cargo pilots").
• Pilots running reserve-heavy, timezone-heavy operations across multiple domiciles (currently ANC, SDF/SDFZ, ONT, MIA).
• Pilots who want to share their schedule read-only with approved colleagues.

Core features

• CrewAccess PDF import — Share extension → PDFKit text extraction → structured trip/leg/duty JSON.
• Timeline tab — chronological view of trips, flights, deadheads, layovers (with hotel info), and manual operational events, in airport-local time.
• Calendar tab (iPad) — 8-week Bid Period grid with trip bars, operational events (RSV/LCO/HOT/RCID/CQ), and personal events (Commute/Medical/Appointment/Other), layered Operational > Bid > Personal.
• Next Flight Countdown — Home Screen Widget (T-12h→T-6h) and Live Activity / Dynamic Island (T-6h→T+6h), auto-switching to "Delayed" after STD.
• Friend Sharing — mutual GEMS-ID approval, read-only sharing via CloudKit Public Database.
• TripBoard "OpenTime" browsing — optional, read-only, requires the user's own credentials; disabled in App Review demo mode.
• LogTen-compatible export.
• CloudKit device-to-device sync — local-wins conflict resolution, tombstone deletes.

Status

• Version 1.2.1 (build 68) — latest as of 2026-06-13 (today's commit on main). See Current State for the note on the older v2.x tags.
• iOS 17.0+, iPhone (portrait-first) and iPad (landscape-optimized, distinct UI).
• All core v1 features are implemented and shipped.
• Recent work has centered on Friend Sharing / Profile CloudKit sync reliability, wrapped up in the v1.2.0/v1.2.1 releases.

2Architecture

Build targets · data flow · storage · CloudKit · invariants

Build targets

All targets are generated from project.yml via XcodeGen.

• TripDataHub — main app (SwiftUI, iOS 17.0+, Swift 5.9, Team 54WZM2U9MK, bundle com.sfune.BidProSchedule).
• TripDataCountdownWidgetExtension — Home Screen Widget + Live Activity for the countdown.
• TripDataShareActionExtension — Share Sheet extension that receives CrewAccess PDFs.
• TripDataHubTests / TripDataHubUITests — unit and UI tests.

Source layout (TripDataHub/)

Models/

Centered on TripModels.swift (PayPeriodSchedule, TripLeg, OpenTimeTrip, FriendConnection), plus CalendarModels, FlightCountdownSupport, FriendScheduleMatching, ProfileModels / ProfileSnapshot, DeviceScheduleModels, RosterParsingModels.

Services/ — logic, parsing, sync

• AppViewModel.swift — central state/orchestration (very large).
• CrewAccessPDFImportService + PDFTripParser — PDFKit text extraction and line-by-line parsing.
• CloudKit services — CrewAccessImportCloudKitService, DeviceScheduleCloudKitService, FriendScheduleCloudKitService, GEMSVerificationCloudKitService, ProfileCloudKitService.
• IATATimeZoneResolver (airport → timezone), BidPeriodService (period boundary math), DomicileSupport.
• TripBoardSyncService / TripBoardAuthService — OpenTime fetch (optional, user-credentialed).
• FlightCountdownCoordinator / NextReportNotificationService.
• TripScheduleSnapshotEncoder (serialize for web viewer / sharing), AppGroupImportHandoff (handoff from share extension), AppReviewDemo (demo-mode flag).

ViewModels / Views / app entry

• ViewModels/ — MVVM root AppViewModel, BrowserViewModel, preview data.
• Views/ — Timeline, Calendar (iPad-specific under Views/iPad/), OpenTime, Settings, Profile, Friends, plus shared helpers (TimelineRowViews, CalendarSupport, MaterialIconView).
• TripDataHubApp.swift — entry point; handles deep link tripdatahub://import?manifest=<id>.

Data flow ① — import pipeline

1. User shares a PDF → share extension accepts public.pdf, copies the file + manifest JSON into the App Group container, and deep-links into the main app.
2. AppGroupImportHandoff reads the manifest/PDF.
3. CrewAccessPDFImportService (PDFKit) extracts text; PDFTripParser parses line-by-line into trip/duty/leg/hotel/crew JSON.
4. CrewAccessTripSummaryStore writes the JSON to Documents/CrewAccessImports/{date}_{tripId}.json — this local JSON is the source of truth (INV-006).
5. On startup, reconcileCrewAccessSchedulesWithImportFiles() rebuilds in-memory state from these files.
6. CloudKit sync (below) mirrors both the raw import files and the parsed snapshot for cross-device availability.

Data flow ② — Timeline & Calendar rendering

• PayPeriodSchedule holds a pay period's trips; TripLeg is an individual flight segment (CrewAccess or OpenTime).
• Timeline — groups legs by pairing (trip id), renders cards in local-airport time, sharing row components across iPhone/iPad (INV-005).
• Calendar (iPad) — CalendarSupport normalizes legs and computes the day index from Bid Period start in UTC (INV-009), rendering the 8-week grid layered Operational > Bid > Personal (INV-010).

Storage

• Local JSON (Documents/CrewAccessImports/) — source of truth for imported schedules.
• App Group container — share-extension ↔ main-app handoff and widget data.
• Keychain — TripBoard credentials.
• UserDefaults / local cache via ScheduleCacheService.

External services

• TripBoard (OpenTime) — tripboard.bidproplus.com / fltops-portal.ups.com. Optional, read-only, requires the user's own credentials. No automated login or MFA bypass. Disabled in demo mode.
• No proprietary crew-system APIs and no CrewAccess scraping (CrewAccess sits behind Zscaler + MFA, so import is manual PDF share only).

CloudKit

Container iCloud.com.sfune.TimelineSchedule, Public Database only (no private DB, no CKShare). See docs/ADR/ADR-001-public-cloudkit-phase1.md.

Synchronization

• Own devices — DeviceScheduleCloudKitService syncs TDHDeviceScheduleSnapshot. Local-wins: if local updatedAt is newer, the remote is rejected (INV-007). On startup, import files must be fetched/reconciled before the local snapshot is overwritten, or a fresh device would wipe its own data.
• Import file sync — CrewAccessImportCloudKitService syncs per-trip raw JSON. Deletes use tombstones (deletedAt) rather than hard deletes, so other devices remove the local file (INV-008).
• Friend sharing — GEMS verification, friend-link approval, and shared schedule/profile push-pull are handled by the respective CloudKit services.

Countdown / Live Activity

The widget extension reads shared schedule data via the App Group. The Home Screen Widget covers T-12h→T-6h; the Live Activity (iOS 16.1+) covers T-6h→T+6h on Lock Screen / Dynamic Island, switching to "Delayed" after STD if the flight hasn't departed. Coordinated by FlightCountdownCoordinator / FlightCountdownSupport.

Invariants

Load-bearing rules every change must respect. Full text in docs/INVARIANTS.md.

3Current State

Version · production features · focus · watchOS · tech debt · tests

Current version

• Version 1.2.1 / build 68 — confirmed in project.yml (all 3 targets); matches the latest commit 681ecba "Release v1.2.1 build 68" (2026-06-13, a freshly cut release).
• Bundle ID com.sfune.BidProSchedule (legacy "BidPro" naming kept at the bundle level).
• Minimum iOS 17.0; iPhone + iPad with distinct UI.

Production features

• CrewAccess PDF import (share extension → App Group → PDFKit extraction → line-based parsing).
• Timeline tab (trips, flights, deadheads, layovers, manual operational events).
• iPad 8-week Bid Period calendar (Operational / Bid / Personal layering).
• Next Flight Countdown (widget T-12h→T-6h + Live Activity T-6h→T+6h, auto "Delayed" after STD).
• Friend Sharing (mutual GEMS ID approval, CloudKit Public DB, no CKShare).
• Manual operational events (RSV-A/B/C/D, LCO, HOT, RCID, CQ12/CQ6).
• Manual personal events (Commute, Medical, Appointment, Other).
• CloudKit device sync (local-wins, tombstone deletes).
• LogTen-compatible export.
• TripBoard "OpenTime" browsing (optional, user-credentialed, read-only, with Auto Fetch on app open).
• App Review demo mode (APPSTORE_REVIEW flag — bypasses GEMS, hides OpenTime/Friends, uses synthetic data; PDF import/Timeline/Calendar remain available).

Recent focus

The last ~12 commits (2026-05 to 06-13) center on Friend Sharing / Profile CloudKit sync reliability: friend timeline sync fixes, request sync recovery/restore, link-permission fallbacks, notify-on-match, preserve-request-on-account-delete. The 2026-06-10 "sync profiles and refresh demo data" change and the v1.2.0/v1.2.1 releases (build 67/68) are the stabilization and release wrap-up of that work.

Several claude/* and feature/* branches exist, but feature/statistics, refactor/consolidate-dedup-layers, etc. are fully merged history — not active work (the exception is watchOS, below). The working tree also has some stale worktrees and untracked files (docs/SIMULATOR_TROUBLESHOOTING.md, TDH-icon-1024.png).

watchOS support DEFERRED

Complete and validated, but not yet integrated into main.

What the investigation found

• A complete watchOS MVP exists only on feature/watchos (single commit d08f733, "v1.0.3 build 55: watchOS MVP (PR1–PR7)", 2026-05-24).
• git merge-base --is-ancestor feature/watchos main → NO; never merged.
• It diverges at b1cf1ff (v1.0.3 build 54), now 20 commits behind main (~3 weeks of Friend Sharing work since).
• Current main has zero watch files; project.yml defines no watch target.

What's on the branch (for reference)

• TripDataHubWatchApp/ (watchOS 10.0, embedded) — Trip/Reserve/Training/OffDuty mode views and a debug picker.
• TripDataHubShared/ — shared types (WatchOperationalMode and the various Payload types).
• WatchConnectivity transport (iPhone generates a snapshot and sends via updateApplicationContext; Watch dedupes/persists across cold launch).
• Tests (WatchSnapshotTests etc., 102/0 passing at authoring) and branch-only docs (validation checklist, known limitations).

Reviving it means rebasing/merging feature/watchos onto current main, resolving ~3 weeks of drift (Friend Sharing and domicile model/service changes landed since b1cf1ff), then re-validating against the branch's checklist.

Known tech debt

• sharedTimelineCards: [WebTimelineCard] (TripModels.swift:156-187) is marked "remove in Phase B+". Unused in-app today; intended for the not-yet-built web viewer.
• CloudKit Dev/Prod drift — schema changes must be manually deployed to Production; mismatches are a named, recurring root cause of friend-sharing bugs (docs/AI_CONTEXT_INDEX.md).
• CHANGELOG / RELEASE_NOTES are stale (stop at v1.0.0); no notes for v1.1.2–v1.2.1.
• README.md is reference data (classification rules + BP/PP date table) under a "BidProSchedule Notes" heading — not a project overview. Low-priority rewrite candidate.
• Calendar V2 items (fatigue overlays, trip editing, drag-and-drop, colleague overlays, real-time ops tracking, month view) are explicitly out of scope — don't pitch them as quick wins.
• Stale worktrees and uncommitted image/doc files sit in the tree — housekeeping, not blockers.

Next work

No forward-looking roadmap doc exists beyond the Roadmap section. The clearest signal is that Friend Sharing / Profile sync just reached a stable release point (v1.2.1 / build 68). Absent a new sync bug, focus is likely to shift toward roadmap items (web timeline viewer, additional countdown variants, Calendar V2).

Test coverage

Unit tests cover: countdown phases/duration/leg selection; calendar day-index, BP/PP membership, DST edge cases; PDF parser regression (golden JSON); device-sync local-wins; LogTen export format; import-file CloudKit sync; GEMS verification sync (incl. the domicile/schemaVersion: 2 field added in build 32+); device snapshot sync; import handoff; profile sync; friend request matching; snapshot encoding; App Group handoff; next-report window calculation. Plus a separate UI test target (TripDataHubUITests).

4Roadmap

Planned (scoped/in progress) · Proposed (future per specs) · Ideas (loose)