# Municipal Transit Planner

A web-based planning tool for municipal transit agencies to evaluate routes, schedules, stops, service coverage, and operational impacts. The planner helps staff compare service scenarios using GTFS data, demographic overlays, ridership assumptions, and configurable policy targets.

## Overview

Municipal Transit Planner is designed for transportation planners, schedulers, and policy analysts who need a practical way to model local bus and shuttle service changes before publishing them. It supports importing existing transit data, drafting route alternatives, estimating vehicle requirements, and reviewing service equity indicators.

The project is intended for internal planning workflows, public engagement preparation, and early-stage feasibility analysis. It is not a real-time dispatching or passenger trip-planning system.

## Features

- Import GTFS feeds for routes, stops, trips, calendars, and shapes
- Create and compare proposed service scenarios
- Draw, edit, and validate route alignments on a map
- Estimate round-trip time, frequency, span of service, and vehicle needs
- Analyze stop spacing and walking access coverage
- Overlay census, equity, employment, school, and healthcare datasets
- Generate scenario summaries for council reports and public meetings
- Export updated GTFS drafts and planning reports
- Configure local service standards and performance thresholds

## Install

### Prerequisites

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

### Setup

Clone the repository:

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

Install dependencies:

```bash
pnpm install
```

Create the local environment file:

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

Create and migrate the database:

```bash
createdb transit_planner
pnpm db:migrate
```

Start the development server:

```bash
pnpm dev
```

The application will be available at:

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

## Usage

### Import a GTFS Feed

From the project directory, run:

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

After import, open the application and select the imported service package from the dashboard.

### Create a Scenario

1. Open an existing service package.
2. Select **New Scenario**.
3. Choose whether to duplicate current service or start from a blank network.
4. Edit routes, stops, schedules, and assumptions.
5. Save the scenario for comparison.

### Compare Scenarios

Use the scenario comparison view to review:

- Total annual service hours
- Peak vehicle requirement
- Route mileage
- Population within walking distance
- Jobs and key destinations served
- Estimated operating cost
- Service standard exceptions

### Export Results

Export a scenario summary:

```bash
pnpm report:scenario scenario_2026_network_update
```

Export a draft GTFS package:

```bash
pnpm gtfs:export scenario_2026_network_update ./exports
```

## Configuration

Configuration is managed through environment variables and agency policy files.

### Environment Variables

| Variable | Description | Default |
| --- | --- | --- |
| `DATABASE_URL` | PostgreSQL connection string | `postgres://localhost/transit_planner` |
| `APP_BASE_URL` | Public application URL | `http://localhost:3000` |
| `MAP_TILE_URL` | Map tile provider URL | OpenStreetMap |
| `DEFAULT_TIMEZONE` | Agency timezone | `America/Toronto` |
| `ENABLE_PUBLIC_SHARING` | Allow read-only public scenario links | `false` |
| `MAX_GTFS_UPLOAD_MB` | Maximum GTFS upload size | `250` |

### Service Standards

Agency planning standards are defined in:

```text
config/service-standards.yml
```

Example:

```yaml
coverage:
  walking_distance_meters: 400
  minimum_population_served_percent: 85

frequency:
  frequent_service_minutes: 15
  base_service_minutes: 30
  maximum_headway_minutes: 60

stops:
  minimum_spacing_meters: 250
  maximum_spacing_meters: 600

costs:
  hourly_operating_cost: 142.50
  annualization_factor: 52
```

### Data Layers

Optional GIS and demographic layers can be configured in:

```text
config/layers.yml
```

Supported layer formats include GeoJSON, Shapefile, and PostGIS tables. Common layers include census blocks, equity priority areas, schools, hospitals, major employers, and municipal boundaries.