🚌 HoosRide - CS 4710 Final Project

Smart transit for UVA. Real-time bus tracking with ML-powered arrival predictions.

HoosRide is an iOS app that helps University of Virginia students and staff navigate the UVA transit system with live bus locations, intelligent trip planning, and machine learning-based arrival time predictions.

---

✨ Features

🗺️ Live Transit Map

• Real-time bus locations on all UVA routes
• Color-coded routes (Orange, Gold, Green, Purple, Silver + Health shuttles)
• Live vehicle positions with heading and load indicators
• Route filtering and nearest-bus detection
• Tap stops to see serving routes; tap vehicles for details

🧭 Smart Trip Planner

• Location-aware routing with Apple Maps integration
• 25+ curated UVA destination aliases (type "JPJ", "O-Hill", "Barracks", etc.)
• Optimized route selection using live vehicle positions
• Walking + transit combined itineraries
• Route explanation badges — tells you why a route was chosen
• Confidence indicators based on active bus count and ML predictions

🤖 ML-Powered Predictions

• CoreML Gradient Boosted Tree model trained on UVA transit data
• Adaptive delay corrections with calibrated confidence scoring
• On-device observation collection for model improvement
• Transparent source tracking (CoreML vs heuristic fallback)

📶 Resilient Data Handling

• Offline / degraded mode with connection state tracking
• Stale data indicators with automatic retry
• JSON-based master route data with hardcoded fallback
• Graceful failure: static routes shown when API is unreachable

---

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                          iOS App (Swift 6)                       │
│                                                                  │
│  ┌──────────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │   SwiftUI Views  │  │ MapKit Map   │  │ CoreML Predictor  │  │
│  │  ContentView     │  │ TransitMap   │  │ MLArrivalPredict. │  │
│  │  TripPlannerView │  │ MapViewModel │  │ ArrivalPredictor  │  │
│  └────────┬─────────┘  └──────┬───────┘  └────────┬──────────┘  │
│           └──────────────┬────┘───────────────────┘              │
│                          │                                       │
│              ┌───────────┴───────────┐                           │
│              │    Routing Engine     │                           │
│              │  Trip planning +      │                           │
│              │  route scoring +      │                           │
│              │  vehicle ETA calc     │                           │
│              └───────────┬───────────┘                           │
│                          │                                       │
│  ┌──────────┐  ┌────────┴────────┐  ┌──────────────────────┐   │
│  │ Location │  │ TranslocService │  │   MasterDataLoader   │   │
│  │ Manager  │  │  (API client)   │  │ (JSON → Swift models)│   │
│  └──────────┘  └────────┬────────┘  └──────────────────────┘   │
└──────────────────────────┼──────────────────────────────────────┘
                           │
                  TransLoc REST API
                  (real-time data)

---

🚀 Getting Started

Requirements

Tool	Version
Xcode	16.0+
iOS	17.0+
Swift	6.0

Quick Start

# Open in Xcode
open HoosRide.xcodeproj

# Build & Run (⌘+R) — targets iPhone simulator
# No API keys needed — TransLoc API is public for UVA

Running Tests

# Run all unit tests (32 tests)
xcodebuild -project HoosRide.xcodeproj -scheme HoosRide \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' test

# Or press ⌘+U in Xcode

Simulator Location

For best results, set the simulator location to UVA:

1. In Simulator: Features → Location → Custom Location
2. Latitude: 38.0356, Longitude: -78.5034

---

📱 Project Structure

HoosRide/
├── HoosRide/
│   ├── HoosRideApp.swift              # App entry point
│   │
│   ├── # Views
│   ├── ContentView.swift              # Trip planner UI + view model
│   ├── MapView.swift                  # Live transit map + MapViewModel
│   ├── TripStepRow.swift              # Individual trip step rendering
│   ├── RouteExplanationBadge.swift    # Why-this-route explanation
│   ├── ConnectionStatusBanner.swift   # Offline/stale data indicator
│   ├── SettingsView.swift             # App settings
│   │
│   ├── # Routing & Planning
│   ├── RoutingEngine.swift            # Route optimization + scoring
│   ├── PlannedTrip.swift              # Trip model + RouteChoiceReason
│   ├── TripStep.swift                 # Walk/ride/transfer/arrival steps
│   │
│   ├── # Data & Services
│   ├── TranslocService.swift          # TransLoc API client
│   ├── MasterData.swift               # Route/stop canonical data
│   ├── master_routes.json             # JSON route configuration
│   ├── UVADestinations.swift          # 25+ curated campus aliases
│   ├── LocationSearchService.swift    # Apple Maps search integration
│   ├── LocationManager.swift          # GPS/location handling
│   ├── GeocodingService.swift         # Address → coordinate
│   ├── GeoUtilities.swift             # Distance, formatting helpers
│   │
│   ├── # ML & Prediction
│   ├── MLArrivalPredictor.swift       # CoreML model wrapper
│   ├── ArrivalPredictor.swift         # Prediction orchestration
│   ├── ObservationCollector.swift     # On-device learning data
│   │
│   ├── # Models
│   ├── TransitModels.swift            # PlaceResult, BusRoute, RouteCandidate
│   ├── TransitSnapshot.swift          # Immutable transit state snapshot
│   ├── TransitStop.swift              # Stop model
│   └── BusVehicle.swift               # Vehicle model
│
└── HoosRideTests/
    └── HoosRideTests.swift            # 32 unit tests

---

🤖 On-Device ML

Current Model Performance

Metric	Value
MAE	1.76 min
R²	0.55
vs Heuristic	50% better

The trained CoreML model (BusArrivalPredictor.mlpackage) ships bundled in the Xcode project — Xcode picks it up automatically at build time. No external toolchain required to build the app.

What's ML vs Heuristic

Component	Source
Wait time estimation	ML (CoreML) when vehicles present; heuristic fallback
Delay adjustment	ML with 50% blending weight
Confidence scoring	Calibrated weighted factors
Ride time	Segment-based heuristic
Walking time	Distance / speed constant

---

📊 UVA Routes

Student Routes

Route	Color	Area
Orange	🟠	JPA ↔ Madison Ave ↔ Stadium
Gold	🟡	Hereford ↔ North Grounds ↔ Barracks Rd
Green	🟢	Hereford ↔ Rugby Rd ↔ Grady Ave
Purple	🟣	Fontaine Research Park ↔ Medical Center
Silver	⚪	JPJ ↔ Emmet St ↔ JPA ↔ North Grounds

Health Shuttles

Route	Description
Fontaine Shuttle	Medical Center ↔ Fontaine Research Park
Health Stadium	Medical Center ↔ Scott Stadium

---

🔧 Key Design Decisions

1. JSON + Hardcoded Fallback for master route data — JSON loads first, hardcoded Swift data serves as safety net
2. Observation pattern (@Observable) over ObservableObject — cleaner SwiftUI integration, no @Published boilerplate
3. Immutable TransitSnapshot for thread-safe routing — snapshot is built once per refresh cycle
4. Walking effort multiplier (1.6×) — a 12-min bus ride beats an 8-min walk because riding is less effort
5. ML blending at 50% — positional ETA as base, ML delay layered on top to avoid overcorrection
6. Degraded mode over crashes — always show something (static routes) rather than empty screen

---

🔌 API

HoosRide uses the TransLoc v1 API (no key required for UVA):

Endpoint	Purpose
/v1/vehicle_statuses	Live bus positions
/v1/arrivals	ETA predictions
/v1/routes	Route metadata

---

🧪 Test Coverage

32 tests across 4 test suites:

• RoutingEngineTests (15): Walk vs bus, stop matching, route preference, edge cases, delayed vehicles
• TransitModelTests (4): PlaceResult detection, route segments, vehicle equality, walking speeds
• GeoUtilitiesTests (6): Distance, heading, formatting
• MLPredictorTests (3): Prediction validity, rush hour detection, ETA adjustment

---

📝 Known Limitations

• Route data requires app update if UVA changes routes (JSON helps but still bundled)
• ETA confidence drops significantly when no active vehicles are tracked
• ML model trained primarily on synthetic data — real-world accuracy improves with observation collection
• Single-seat trips only — no transfer routing between different bus lines
• Walking time estimates use straight-line distance (no sidewalk routing)

---

📄 License

MIT License — see LICENSE for details.

---

Built for UVA students who wait at bus stops. 🧡💙