# Municipal Transit Planner

A web application for planning, modeling, and reviewing municipal transit service changes. The planner helps transit agencies evaluate routes, stops, schedules, vehicle needs, accessibility coverage, and rider impacts before publishing service updates.

## Overview

Municipal Transit Planner is designed for city transportation departments, transit authorities, and planning consultants who need a shared workspace for day-to-day network planning. It combines GTFS data, local policy assumptions, geographic layers, and scenario modeling into a single planning interface.

The application supports early-stage service design, public review preparation, and internal operations planning.

## Features

- Import and validate GTFS feeds
- View routes, stops, trips, headways, and service calendars on an interactive map
- Create planning scenarios without modifying the baseline network
- Add, remove, or relocate stops
- Draft new routes and edit existing alignments
- Compare service frequency, span, coverage, and vehicle requirements
- Estimate stop-level and route-level accessibility coverage
- Export updated GTFS files for review or downstream scheduling tools
- Configure local planning standards such as walking distance, service targets, and operating assumptions
- Role-based access for planners, reviewers, and administrators

## Install

### Requirements

- Node.js 20 or newer
- PostgreSQL 15 or newer
- PostGIS 3 or newer
- npm 10 or newer

### Setup

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

Create a local environment file:

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

Create the database:

```bash
createdb transit_planner
psql transit_planner -c "CREATE EXTENSION postgis;"
```

Run migrations:

```bash
npm run db:migrate
```

Start the development server:

```bash
npm run dev
```

The application will be available at:

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

## Usage

### Import a GTFS Feed

```bash
npm run gtfs:import -- ./data/current-feed.zip
```

After import, open the application and select the imported feed from the Network Library.

### Create a Planning Scenario

1. Open the baseline network.
2. Select **New Scenario**.
3. Enter a scenario name, planning horizon, and description.
4. Edit routes, stops, schedules, or service assumptions.
5. Use the comparison panel to review changes against the baseline.

### Run Scenario Metrics

```bash
npm run metrics:scenario -- --scenario spring-2027-frequency-plan
```

Metrics include:

- Population within walking distance of stops
- Jobs within walking distance of stops
- Route miles
- Revenue hours
- Peak vehicle requirement
- Average headway by service period
- Stops without accessible pedestrian connections

### Export a Scenario

```bash
npm run gtfs:export -- --scenario spring-2027-frequency-plan --out ./exports/spring-2027.zip
```

The exported GTFS package can be used for review, validation, scheduling, or publication workflows.

## Configuration

Configuration is managed with environment variables.

```env
DATABASE_URL=postgres://localhost:5432/transit_planner
APP_PORT=3000
APP_BASE_URL=http://localhost:3000

GTFS_UPLOAD_DIR=./data/uploads
GTFS_EXPORT_DIR=./exports

DEFAULT_TIMEZONE=America/Toronto
DEFAULT_WALK_DISTANCE_METERS=400
DEFAULT_SERVICE_DAY_START=04:00
DEFAULT_SERVICE_DAY_END=27:00

MAP_TILE_URL=https://tile.openstreetmap.org/{z}/{x}/{y}.png
GEOCODER_PROVIDER=nominatim
GEOCODER_BASE_URL=https://nominatim.openstreetmap.org

AUTH_ENABLED=false
SESSION_SECRET=change-me
```

### Key Options

| Variable | Description | Default |
| --- | --- | --- |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `APP_PORT` | Local application port | `3000` |
| `GTFS_UPLOAD_DIR` | Directory for uploaded GTFS feeds | `./data/uploads` |
| `GTFS_EXPORT_DIR` | Directory for exported GTFS packages | `./exports` |
| `DEFAULT_TIMEZONE` | Agency timezone used for schedules | `America/Toronto` |
| `DEFAULT_WALK_DISTANCE_METERS` | Walking access distance for coverage analysis | `400` |
| `MAP_TILE_URL` | Map tile endpoint used by the web client | OpenStreetMap |
| `AUTH_ENABLED` | Enables login and role-based access control | `false` |
| `SESSION_SECRET` | Secret used to sign user sessions | Required in production |

## Production Notes

For production deployments:

- Set `AUTH_ENABLED=true`
- Use a strong `SESSION_SECRET`
- Store uploaded and exported GTFS files on durable storage
- Run PostgreSQL with regular backups
- Use HTTPS for all public deployments
- Configure a production-grade map tile provider if usage exceeds public tile limits

## License

MIT