Back to MusePages

Loopline — A Clearer Commute

The original prompt, shown in full as plain text.

Prompt

# Caltrain Commuter App - Product Requirements Document (Next.js)

## 1. Overview

### 1.1 Purpose
Build a Next.js web application that helps Caltrain commuters plan their trips by providing real-time train schedules and weather information at their destination station.

### 1.2 Target Users
- Daily Caltrain commuters traveling between San Francisco and San Jose
- Occasional riders who need quick schedule information
- Bay Area residents planning trips along the Peninsula

### 1.3 Core Value Proposition
A single dashboard that answers: "When's my next train, and what's the weather like at both my origin and destination?"

## 2. Core Features

### 2.1 Station Selection
**Description:** Allow users to select origin and destination stations.

**Requirements:**
- Dropdown menus or searchable select components for both origin and destination
- List all Caltrain stations (complete station list from San Francisco to Gilroy)
- Swap button to quickly reverse origin/destination
- Input validation to prevent selecting the same station for both origin and destination

### 2.2 Next Trains Display
**Description:** Show upcoming train departures from the origin station.

**Requirements:**
- Display at least the next 5 upcoming trains
- For each train, show:
  - Departure time from origin station
  - Arrival time at destination station
  - Trip duration
  - Train direction (Northbound/Southbound)
  - Train number/type (Local/Limited/Express if available)
- Highlight the next immediate departure
- Auto-refresh every 60 seconds
- Show loading states during data fetch
- Display clear messaging if no trains are available

### 2.3 Weather Information
**Description:** Display current weather and forecast for both origin and destination stations.

**Requirements:**
- Show weather for both origin and destination stations side-by-side (or stacked on mobile)
- Current weather conditions for each station:
  - Temperature (°F)
  - Weather description (e.g., "Partly Cloudy")
  - Weather icon
  - Wind speed
  - Humidity percentage
- 3-hour forecast or next few hours for destination
- Visual weather icons/imagery
- Clearly label which weather belongs to which station
- Highlight significant weather differences between stations (e.g., "10° warmer at destination")

### 2.4 Service Alerts
**Description:** Display any service disruptions or important notices.

**Requirements:**
- Show active Caltrain service alerts if available
- Highlight delays or schedule changes
- Display advisory messages (e.g., bike car availability)
- Visually distinguish alerts by severity (info, warning, critical)

### 2.5 Saved Routes
**Description:** Allow users to save frequently used routes.

**Requirements:**
- Save up to 5 favorite routes with custom names (e.g., "Home to Work")
- Quick access buttons/cards for saved routes
- Edit and delete functionality for saved routes
- Store in browser localStorage
- Pre-populate origin and destination when selecting a saved route

## 3. Technical Requirements

### 3.1 Framework & Stack
- **Framework:** Next.js 14+ (App Router) - **REQUIRED**
- **Language:** TypeScript
- **Styling:** Tailwind CSS
- **State Management:** React hooks (useState, useEffect)
- **Data Fetching:** Next.js Server Components where possible, with client-side updates using React Query or SWR
- **Storage:** localStorage for saved routes
- **Deployment:** Vercel (recommended for Next.js apps)

**Note:** This application MUST be built using Next.js. Do not use Create React App, Vite, or any other framework.

### 3.1a Next.js Specific Features to Leverage
- **App Router** - Use the modern App Router (not Pages Router)
- **Server Components** - Fetch initial data server-side for better performance
- **API Routes** - Create `/api/trains` and `/api/weather` endpoints
- **Server Actions** (optional) - For form submissions if needed
- **Image Optimization** - Use `next/image` for weather icons
- **Metadata API** - Set proper page titles and descriptions
- **Loading States** - Use `loading.tsx` files for route-level loading UI
- **Error Handling** - Use `error.tsx` files for error boundaries

### 3.2 API Integrations

#### Caltrain Schedule Data
**Option 1: 511.org Transit API**
- Endpoint: https://api.511.org/transit/
- Requires free API key registration
- Provides real-time arrivals and GTFS data

**Option 2: Static GTFS Schedule**
- Download Caltrain GTFS feed
- Parse schedule locally for train times
- Less real-time but simpler implementation

**Implementation:**
- Create API route in Next.js (`/api/trains`)
- Cache responses appropriately
- Handle API errors gracefully

#### Weather API
**OpenWeatherMap API (Free Tier)**
- Endpoint: https://api.openweathermap.org/data/2.5/
- Requires free API key
- Use current weather and forecast endpoints
- Map each Caltrain station to lat/long coordinates

**Implementation:**
- Create API route in Next.js (`/api/weather`)
- Cache weather data for 10-15 minutes
- Store station coordinates in a configuration file

### 3.3 Station Data
Create a static configuration file with:
```typescript
interface Station {
  id: string;
  name: string;
  code: string; // For API queries
  coordinates: {
    lat: number;
    lng: number;
  };
}
```

Include all Caltrain stations (32 stations total):

**Northbound (San Francisco to Gilroy):**
- San Francisco (4th & King)
- 22nd Street
- Bayshore
- South San Francisco
- San Bruno
- Millbrae
- Broadway
- Burlingame
- San Mateo
- Hayward Park
- Hillsdale
- Belmont
- San Carlos
- Redwood City
- Atherton
- Menlo Park
- Palo Alto
- Stanford
- California Ave
- San Antonio
- Mountain View
- Sunnyvale
- Lawrence
- Santa Clara
- College Park
- San Jose Diridon
- Tamien
- Capitol
- Blossom Hill
- Morgan Hill
- San Martin
- Gilroy

### 3.4 Responsive Design
- Mobile-first approach
- Breakpoints: mobile (default), tablet (768px), desktop (1024px)
- Touch-friendly interface elements
- Optimized for quick glance on mobile devices

## 4. User Stories

### Story 1: Quick Commute Check
**As a** daily commuter  
**I want to** quickly see my next train and weather at both origin and destination  
**So that** I can decide when to leave and what to wear

**Acceptance Criteria:**
- Default landing page shows station selectors
- Selecting saved route loads data within 2 seconds
- Weather for both stations and train times are clearly visible above the fold
- Can easily compare weather conditions between origin and destination

### Story 2: Save Favorite Route
**As a** regular commuter  
**I want to** save my daily commute route  
**So that** I don't have to select stations every time

**Acceptance Criteria:**
- "Save Route" button visible after selecting stations
- Can name the saved route
- Saved route persists across browser sessions
- Can access saved route from homepage

### Story 3: Check Service Status
**As a** commuter  
**I want to** see if there are any delays  
**So that** I can adjust my travel plans

**Acceptance Criteria:**
- Service alerts displayed prominently if present
- Alerts update automatically
- Different visual treatment for different alert types

## 5. User Interface Requirements

### 5.1 Layout
- Clean, minimal design focused on information clarity
- High contrast for outdoor readability
- Large, easily tappable buttons (min 44x44px)
- Consistent spacing and typography

### 5.2 Color Scheme
- Primary: Caltrain red (#E31837) for branding
- Accent: Blue for interactive elements
- Success: Green for on-time status
- Warning: Yellow/Orange for delays
- Background: Light neutral colors

### 5.3 Components
- Station selector (dropdown/combobox)
- Train card showing departure info
- Weather widget with icon and temperature
- Alert banner for service notices
- Saved route card/button
- Loading skeletons for async data

## 6. Non-Functional Requirements

### 6.1 Performance
- Initial page load under 3 seconds on 3G
- Time to interactive under 5 seconds
- Optimize images and icons
- Implement loading states for all async operations

### 6.2 Accessibility
- WCAG 2.1 AA compliance
- Keyboard navigation support
- Screen reader friendly
- Proper ARIA labels
- Sufficient color contrast ratios

### 6.3 Error Handling
- Graceful degradation if APIs are unavailable
- Clear error messages for users
- Retry mechanisms for failed requests
- Fallback to cached data when possible

### 6.4 Browser Support
- Chrome, Firefox, Safari, Edge (latest 2 versions)
- iOS Safari, Chrome Mobile
- Progressive enhancement approach

## 7. Future Enhancements (Out of Scope for V1)

### 7.1 Advanced Features
- Push notifications for saved routes
- Real-time train tracking on map
- Multi-leg journey planning with connections
- Calendar integration for recurring commutes
- Historical delay data and reliability scores

### 7.2 Premium Features
- Crowding predictions based on historical data
- Alternative route suggestions during delays
- Integration with ride-sharing for last-mile connections
- Bike car availability tracking

### 7.3 Social Features
- Share trip plans with friends
- Commute buddy matching
- Community-reported issues

## 8. Success Metrics

### 8.1 Key Performance Indicators
- Daily active users
- Average session duration
- Saved route creation rate
- API response time
- Error rate

### 8.2 User Satisfaction
- Time to complete primary task (find next train)
- Return user rate
- Saved route usage percentage

## 9. Development Phases

### Phase 1: MVP (Week 1-2)
- Station selection UI
- Next trains display (static or simple API)
- Basic weather display
- Responsive layout

### Phase 2: Enhancement (Week 3)
- Saved routes functionality
- Service alerts integration
- Auto-refresh
- Error handling improvements

### Phase 3: Polish (Week 4)
- Performance optimization
- Accessibility audit
- Cross-browser testing
- Documentation

## 10. Technical Constraints

- Must work without user authentication (for simplicity)
- Data stored client-side only (localStorage)
- Free-tier API limits must be respected
- No backend database required for V1

## 11. API Keys Required

Development will require:
1. 511.org API key (free) OR access to Caltrain GTFS data
2. OpenWeatherMap API key (free tier)

Store in `.env.local` (Next.js environment variables):
```
TRANSIT_API_KEY=your_key_here
WEATHER_API_KEY=your_key_here
```

**Note:** In Next.js, prefix with `NEXT_PUBLIC_` if you need to access these in client components, otherwise keep them server-side only for security.

## 12. Project Structure (Next.js App Router)

```
caltrain-commuter/
├── app/
│   ├── page.tsx (main dashboard)
│   ├── layout.tsx
│   └── api/
│       ├── trains/route.ts
│       └── weather/route.ts
├── components/
│   ├── StationSelector.tsx
│   ├── TrainList.tsx
│   ├── WeatherWidget.tsx
│   ├── ServiceAlerts.tsx
│   └── SavedRoutes.tsx
├── lib/
│   ├── stations.ts (station data)
│   ├── types.ts (TypeScript interfaces)
│   └── utils.ts
├── public/
│   └── icons/
├── styles/
├── next.config.js
├── tailwind.config.js
└── tsconfig.json
```

**Initialize with:**
```bash
npx create-next-app@latest caltrain-commuter --typescript --tailwind --app
```

## 13. Acceptance Criteria

The MVP is complete when:
- [ ] User can select origin and destination stations
- [ ] Next 5 trains are displayed with times and direction
- [ ] Current weather for destination is shown
- [ ] User can save at least one favorite route
- [ ] App is responsive on mobile and desktop
- [ ] No critical bugs or broken functionality
- [ ] Basic error handling is in place