# Building a Municipal Transit Planner That Works in the Real World

Municipal transit planning is rarely a clean shortest-path problem. A useful planner must combine scheduled service, walking connections, transfer rules, accessibility constraints, and real-time disruptions while still responding quickly enough for mobile clients and station displays. Our system models the network as a time-dependent graph: stops are vertices, scheduled trips are edges, and transfer paths connect nearby platforms or stations.

## Turning Public Data into a Reliable Graph

The planner imports GTFS feeds from bus, streetcar, subway, and regional operators. During ingestion, it validates stop references, removes impossible trip sequences, normalizes agency-specific route identifiers, and expands calendar exceptions into service dates. We build immutable daily graph snapshots so routing requests never observe partially imported data, while retaining the original feed version for audit and rollback.

```yaml
routing:
  max_transfers: 3
  walking_speed_mps: 1.25
  transfer_buffer_seconds: 120
  wheelchair_accessible_only: false
```

## Routing Beyond the Fastest Arrival

A modified RAPTOR algorithm evaluates trips by rounds, with each round representing another transfer. The search tracks arrival time, walking distance, transfer count, and accessibility state rather than collapsing every tradeoff into a single weight. This lets the API return practical alternatives—for example, a slightly slower one-seat ride alongside a faster itinerary requiring two transfers.

## Applying Real-Time Service Updates

Vehicle positions are useful for map displays, but trip updates and service alerts have greater routing value. We map incoming GTFS-Realtime entities to the active graph snapshot, reject stale observations, and apply delays through a small overlay instead of rebuilding the graph. Cancelled trips are disabled immediately, while uncertain delays are capped to prevent a single faulty agency update from producing implausible itineraries.

## Operating and Evaluating the Planner

Production monitoring focuses on more than request latency. We track failed itinerary searches by neighborhood, transfer success at major hubs, feed freshness, accessibility coverage, and differences between predicted and observed arrival times. Nightly replay tests run historical requests against new graph builds, helping planners catch regressions such as a removed pedestrian connection or an overly aggressive transfer buffer before deployment.