🚇 MBTA Live

Real-time train arrivals and smart commute planning for Boston's MBTA subway system.

🔗 Live Demo → mbtalive.vercel.app

---

About

MBTA Live is a cross-platform transit app that provides real-time train arrival predictions, schedule data, and intelligent commute planning for all MBTA subway lines (Red, Orange, Blue, Green, Mattapan). Built with Flutter to deliver full cross-platform support with arrivals tracking, commute planning and arrival notifications.

Key Features

• Live Arrivals — Real-time predictions merged with schedule data, auto-refreshing every 30 seconds
• Smart Commute Planner — 4-step wizard to configure daily commutes with personalized leave-by notifications
• Nearest Station Detection — GPS-based location lookup across 100+ MBTA stations using optimized parallel API calls
• Direction Filtering — Filter arrivals by destination with horizontal scrollable chips
• Favorites — Save frequently used route + station combinations for quick access
• Commute Cards — Contextual home screen card showing your next commute with nearby train times and a countdown
• Onboarding Flow — 3-page onboarding with name personalization and notification setup
• Dark Mode — Full Material 3 theming with automatic light/dark mode support

---

Tech Stack

Layer	Technology
Framework	Flutter (Dart)
State Management	Provider (ChangeNotifier)
Networking	Dio — concurrent API calls with error handling and retry logic
API	MBTA V3 REST API (predictions, schedules, routes, stops)
Local Storage	SharedPreferences (favorites, commutes, user settings)
Location	Geolocator (GPS-based nearest station)
Deployment	Vercel (web), Android (APK), iOS-ready

---

Architecture

lib/
├── main.dart                  # App entry point, onboarding check, Provider setup
├── models/                    # Data classes (TrainArrival, Commute, Favorite, etc.)
├── services/                  # API layer, persistence, location, commute engine
│   ├── mbta_service.dart      # All MBTA API calls with concurrent fetch + merge
│   ├── commute_manager.dart   # Commute CRUD + user profile (SharedPreferences)
│   ├── commute_engine.dart    # Leave-by time calculation, train selection logic
│   ├── location_manager.dart  # GPS permissions + current position
│   └── user_settings.dart     # Favorites + route/stop persistence
├── providers/
│   └── train_provider.dart    # Main ViewModel — state, auto-refresh, rate limiting
├── screens/                   # Full-screen views (arrivals, commutes, settings, etc.)
├── widgets/                   # Reusable UI components (ArrivalRow, CommuteCard, etc.)
└── theme/                     # MBTA brand colors + Material 3 theme config

How Arrivals Work

1. Concurrent fetch — Predictions and schedules are fetched in parallel via Future.wait()
2. Smart merge — Predictions take priority; schedules fill gaps for trips without real-time data
3. Direction extraction — Unique destinations are extracted from arrivals for the filter pills
4. Auto-refresh — A 30-second timer reloads data, with rate limiting to prevent redundant calls
5. Sibling stop IDs — Multi-platform stations (e.g., Green Line surface stops) query all child stop IDs for complete coverage

How Nearest Station Works

Optimized from 22+ sequential API calls down to 3 parallel requests:

1. GET /stops?filter[route_type]=0,1 — All subway stops in one call
2. GET /routes?filter[type]=0,1 — All routes (fetched in parallel)
3. GET /routes?filter[stop]={id} — Which route serves the nearest stop

---

Getting Started

Prerequisites

• Flutter SDK 3.11+
• Dart 3.11+

Setup

git clone https://github.com/yourusername/mbtalive.git
cd mbtalive
flutter pub get
flutter run

To run on web:

flutter run -d edge    # or chrome

To build for production:

flutter build web --release
flutter build apk --release

API Key (Optional)

The app works without an API key using the public MBTA V3 endpoint (20 req/min limit). For higher rate limits, get a free key from api-v3.mbta.com and add it in lib/services/mbta_service.dart:

static const String _apiKey = 'your-key-here';

---

Migration from iOS

This app was originally built in Swift/SwiftUI for iOS, then migrated to Flutter. The migration involved porting all 20 source files:

iOS (Swift)	Flutter (Dart)	Notes
SwiftUI Views	Flutter Widgets	Declarative UI paradigm
@StateObject / @Published	Provider + ChangeNotifier	Reactive state management
URLSession + async let	Dio + Future.wait()	Concurrent network calls
UserDefaults	SharedPreferences	Local persistence
CoreLocation	Geolocator	GPS + permissions
DateComponents	TimeOfDay + DateTime	Date/time math

---

License

This project is for educational and portfolio purposes.