TimeThrottle_Full_Project_Breakdown.txt

TimeThrottle — Full Project Breakdown (v1.4.3)

1. WHAT THE APP IS

TimeThrottle is an iPhone Live Drive pace-analysis app built around one simple question:

"How much time did speed really buy you?"

It is not a built-in turn-by-turn navigation app.

It uses Apple Maps as the route lookup and ETA-baseline layer, then tracks a real drive to show:
- Time Above Set Speed
- Time Below Set Speed
- projected arrival versus the Apple Maps ETA baseline

In Live Drive, the app can optionally hand off visible navigation to Apple Maps, Google Maps, or Waze while TimeThrottle keeps doing the trip tracking and pace analysis.

2. WHAT THE APP DOES NOW

As of v1.4.3, the app is intentionally centered around one main experience:
1) Live Drive

A. Live Drive
This is the real-time driving mode and the app’s full product focus.

It lets the user:
- choose a route baseline from Apple Maps
- start from Current Location by default
- use Apple Maps-style address autocomplete
- calculate route options
- choose a route
- preview the route before starting
- start a live tracked trip
- see Time Above Set Speed / Time Below Set Speed during the drive
- pause, resume, and end the trip
- save the finished trip
- share a finished-trip summary
- reopen past trips in Trip History

Live Drive setup includes:
- From
- To
- Route options
- Selected route
- Apple ETA
- Map preview
- Desired Speed
- Start Drive

Live Drive while active includes:
- current speed
- elapsed trip time / trip status
- Apple Maps ETA
- projected arrival / live arrival context
- Time Above Set Speed
- Time Below Set Speed
- distance
- Pause / Resume
- End Trip
- optional in-app compact HUD
- route/map context
- optional external navigation handoff

Live Drive finished-trip flow includes:
- result-first summary
- overall result / verdict
- key trip stats
- shareable summary
- Trip History save path

3. BIGGEST CURRENT FEATURES

- compact in-app Live Drive HUD
- Apple Maps route lookup / route options / route preview / ETA baseline
- external navigation handoff to Apple Maps / Google Maps / Waze / Ask Every Time
- Trip History
- shareable finished-trip summaries

4. CURRENT WORDING / PRODUCT FRAMING

The app now uses direct pace-based wording.

Examples:
- Time Above Set Speed
- Time Below Set Speed
- Apple Maps ETA
- projected arrival

The app remains careful not to claim:
- built-in turn-by-turn navigation
- lane guidance
- road speed-limit ownership
- live traffic intelligence it does not truly own

5. DEVELOPMENT HISTORY

- early stage: simpler iPhone pace-analysis concept
- Apple Maps baseline stage: route lookup, route options, route preview, ETA baseline
- Live Drive expansion stage: GPS tracking, route context preservation, finished-trip persistence
- handoff stage: Apple Maps / Google Maps / Waze support
- HUD stage: compact Live Drive HUD
- v1.4.2: Live Drive-only simplification, removed non-Live product paths, improved HUD map follow behavior
- v1.4.3: HUD wording polish, desired-speed input cleanup, consolidated trip summaries, and destination-time-zone arrival formatting

6. WHAT THE AGENTS DO

Dan — Implementation
- app code
- architecture
- tracking logic
- Apple Maps route integration
- navigation handoff system
- Current Location defaulting
- Apple Maps autocomplete
- Trip History
- HUD implementation
- release prep
- Git pushes
- simulator/build/archive prep

Steve — UI / UX Design
- HUD layout direction
- spacing / hierarchy / clarity audits
- wording tone
- route-entry cleanup
- finish-screen UX
- release copy direction

Joe — QA / Release Review
- QA passes
- regression review
- truthfulness review
- state consistency review
- release readiness
- permission-state review
- wording risk evaluation

7. CURRENT FOLDER STRUCTURE

SPEED APP
├── Assets.xcassets
├── build
├── dist
├── Resources
├── scripts
├── Sources
│   ├── Core
│   ├── iOS
│   └── SharedUI
├── Tests
├── CHANGELOG.md
├── privacy-policy.md
├── README.md
├── Package.swift
├── TimeThrottle.xcodeproj
└── dist-ios

Important current files include:
- LiveDriveTracker.swift
- TripAnalysisEngine.swift
- PaceAnalysisMath.swift
- TripHistoryStore.swift
- RouteComparisonView.swift
- RouteModels.swift
- NavigationHandoffService.swift
- TripHistoryViews.swift
- LiveDriveHUDView.swift
- LiveDriveHUDMapView_iOS.swift
- TimeThrottleApp_iOS.swift
- IOSRouteComparisonScreen.swift
- RoutePreviewMapView_iOS.swift

8. RELEASE STATE RIGHT NOW

Current version:
- Version: 1.4.3
- Build: 7

Current release story:
TimeThrottle 1.4.3 is a Live Drive-focused polish release.

It:
- polishes the Current Speed HUD and Avg Spd pill
- updates wording around Apple Maps ETA and desired speed
- keeps Apple Maps as the route lookup / ETA-baseline layer
- keeps the HUD map follow and recenter behavior
- keeps the finished-trip story focused on Time Above Set Speed, Time Below Set Speed, and projected arrival versus Apple Maps ETA baseline

9. CURRENT PRODUCT SUMMARY

TimeThrottle is now a Live Drive-first iPhone pace-analysis app. It uses Apple Maps as the route and ETA-baseline layer, tracks real trips, supports optional external navigation handoff, saves completed trips locally, and focuses the product on Time Above Set Speed, Time Below Set Speed, and projected arrival versus Apple Maps ETA baseline.