TransitMatters Shutdown Tracker

This is the repository for the TransitMatters Shutdown Tracker. Client code is written in Typescript with React and vite, and the minimal backend is written in Python with Chalice.

Requirements to develop locally

• node 22.x and npm 10+ required
  • verify with node -v
• Python 3.13 with recent uv
• With mise installed, mise trust && mise install sets up both (versions are pinned in .nvmrc / .python-version)

Development Instructions

1. In the root directory, run npm install to install all frontend and backend dependencies
2. Run npm start to start both the Vite development server and the Python backend at the same time.
   1. npm run dev to just run the Vite development server
   2. npm run start-python to just run the Chalice backend server
3. Navigate to http://localhost:3000 (or the url provided after running npm start)

Project Structure

src/
  api/              # React Query client for the backend (travel times) and response types
  components/
    charts/         # Chart.js wrappers (travel times, aggregate line chart, etc.)
    maps/           # Line strip-map visualizations
    Shutdowns/      # Shutdown cards, details, dialogs, timeline
  constants/
    shutdowns.json  # Source of truth for all tracked shutdowns
    shutdowns.ts    # Hydrates the JSON into typed Shutdown objects
    stations.json   # Canonical station names per rapid transit line
    cr_stations.json # Canonical station names per Commuter Rail route
  hooks/            # Custom React hooks
  routes/           # TanStack Router file routes
  routeTree.gen.ts  # Generated by TanStack Router; don't edit by hand
  utils/            # Date, time, theme, chart, and travel-time helpers
  store.ts          # Zustand store (line and range filters, dark mode, selected shutdown)
  types.ts          # Shared types (Shutdown, Station, etc.)
server/
  app.py            # Chalice API entry point
  chalicelib/       # S3 cache for upstream TransitMatters Performance API responses
sort-shutdowns.py   # Sorts and checks shutdowns.json

The backend proxies and caches requests to the TransitMatters Performance API in S3, so no MBTA API key is needed. A CloudFront distribution in front of the API caches responses at the edge for as long as each route's Cache-Control allows (the /calendar feed until the next deploy), and deploy.sh clears it on every deploy.

Shutdown Data

src/constants/shutdowns.json is the authoritative list of shutdowns, keyed by line: green, red, orange, blue, and one key per Commuter Rail route (CR-Haverhill, CR-Worcester, ...). Every key should be present, even with an empty array. Mattapan Line shutdowns aren't currently tracked. Each entry has:

• start_station, end_station: must match station names in src/constants/stations.json (rapid transit) or src/constants/cr_stations.json (Commuter Rail)
• start_date, stop_date: YYYY-MM-DD
• alert: link to the MBTA announcement
• reason (optional): free-form note, e.g. "Starting at approximately 6pm on May 14"

The MBTA usually announces service changes in a monthly press release. When adding shutdowns, check station names against stations.json and use the specific press-release URL for alert rather than a generic /alerts link.

cr_stations.json is generated from the Commuter Rail station files in t-performance-dash (common/constants/cr_constants/), with branches added for the Newburyport/Rockport, Providence/Stoughton, Franklin/Foxboro, and Fall River/New Bedford branches so the strip map shows the right stops.

After editing, run npm run sort-shutdowns. CI checks the sort order as part of npm run lint-frontend.

Deployment Instructions

1. Configure AWS CLI 1.x or 2.x with your AWS access key ID and secret under the profile name transitmatters.
2. Configure shell environment variables for AWS ACM domain certificates.
   • TM_LABS_WILDCARD_CERT_ARN
   • (You may also need to set AWS_DEFAULT_REGION in your shell to us-east-1. Maybe not! We're not sure.)
   • DD_API_KEY (Datadog API key, needed to deploy to TransitMatters stack in prod)
3. Execute ./deploy.sh.

Additional notes:

• If you're on a platform with a non-GNU sed, deploy.sh might fail. On macOS, this is fixed by brew install gnu-sed and adding it to your PATH.
• If you get an unexplained error, check the CloudFormation stack status in AWS Console. Good luck!

Linting

To lint frontend and backend code, run npm run lint in the root directory

To lint just frontend code, run npm run lint-frontend

To lint just backend code, run npm run lint-backend

VSCode

If you're using VSCode, .vscode contains a based default workspace setup. It also includes recommended extentions that will improve the dev experience. This config is meant to be as small as possible to enable an "out of the box" easy experience for handling eslint.

Support TransitMatters

If you've found this app helpful or interesting, please consider donating to TransitMatters to help support our mission to provide data-driven advocacy for a more reliable, sustainable, and equitable transit system in Metropolitan Boston.