# Municipal Transit Planner

A web-based planning tool for municipal transit agencies to model routes, stops, schedules, service coverage, and operational impacts before publishing changes to riders.

Municipal Transit Planner helps planners evaluate proposed network updates using GTFS data, census boundaries, stop spacing rules, travel-time assumptions, and service-level targets. It is designed for internal planning teams working on bus, streetcar, light rail, and demand-response networks.

## Features

- Import existing GTFS feeds for routes, stops, trips, calendars, and shapes
- Create and edit proposed routes, stops, stop sequences, and service spans
- Compare current and proposed networks side by side
- Estimate route length, cycle time, vehicle requirements, and service frequency
- Analyze stop coverage by walking distance, population, jobs, schools, and key destinations
- Validate schedules against layover, headway, and span-of-service rules
- Export proposed service plans as GTFS, GeoJSON, CSV, and PDF summaries
- Support multiple planning scenarios per municipality or service area
- Configure local planning standards such as maximum stop spacing and walk-access thresholds

## Install

### Requirements

- Node.js 20 or later
- PostgreSQL 15 or later
- PostGIS 3 or later
- pnpm 9 or later

### Setup

```bash
git clone https://github.com/example/municipal-transit-planner.git
cd municipal-transit-planner
pnpm install
```

Create a local environment file:

```bash
cp .env.example .env
```

Create and migrate the database:

```bash
pnpm db:migrate
pnpm db:seed
```

Start the development server:

```bash
pnpm dev
```

The application will be available at:

```text
http://localhost:3000
```

## Usage

### Import a GTFS Feed

```bash
pnpm gtfs:import ./data/current-service.zip
```

After import, open the planner and create a new scenario from the imported baseline network.

### Create a Planning Scenario

1. Open `Scenarios`
2. Select `New Scenario`
3. Choose a baseline GTFS feed
4. Enter a scenario name, planning year, and service area
5. Save the scenario

### Edit Routes and Stops

Use the map editor to adjust route alignments, add or remove stops, and update stop sequences. Changes are saved to the active scenario and do not modify the baseline feed.

### Run Analysis

```bash
pnpm analyze --scenario spring-2027-network
```

The analysis report includes estimated vehicle needs, route mileage, coverage changes, stop access, and service-level warnings.

### Export a Scenario

```bash
pnpm gtfs:export --scenario spring-2027-network --output ./exports/spring-2027-gtfs.zip
```

## Configuration

Configuration is managed with environment variables.

```env
DATABASE_URL=postgres://planner:planner@localhost:5432/transit_planner
APP_BASE_URL=http://localhost:3000
DEFAULT_TIMEZONE=America/Toronto
DEFAULT_WALK_SPEED_KMH=4.8
DEFAULT_WALK_ACCESS_METERS=400
MAX_STOP_SPACING_METERS=500
MIN_LAYOVER_MINUTES=6
GTFS_UPLOAD_LIMIT_MB=250
MAP_TILE_URL=https://tile.openstreetmap.org/{z}/{x}/{y}.png
```

### Key Settings

| Variable | Description |
| --- | --- |
| `DATABASE_URL` | PostgreSQL connection string with PostGIS enabled |
| `APP_BASE_URL` | Public URL used for links and exported reports |
| `DEFAULT_TIMEZONE` | Default timezone for schedules and service calendars |
| `DEFAULT_WALK_SPEED_KMH` | Walking speed used for access calculations |
| `DEFAULT_WALK_ACCESS_METERS` | Default walk-access buffer around stops |
| `MAX_STOP_SPACING_METERS` | Warning threshold for stop spacing analysis |
| `MIN_LAYOVER_MINUTES` | Minimum layover used when estimating cycle time |
| `GTFS_UPLOAD_LIMIT_MB` | Maximum GTFS upload size |
| `MAP_TILE_URL` | Tile provider URL used by the map interface |

## License

MIT