# Municipal Transit Planner

A planning toolkit for evaluating bus and light-rail service changes across a municipal transit network. The application helps planners model routes, stops, schedules, headways, coverage, and scenario impacts before changes are published.

## Overview

Municipal Transit Planner provides a browser-based map interface and analysis backend for building service scenarios from GTFS data, local census layers, and operational constraints. It is intended for planning departments, transit agencies, and consultants who need repeatable, data-backed workflows for service design.

## Features

- Import GTFS feeds for routes, stops, trips, calendars, and shapes
- Create and compare service scenarios without modifying the base network
- Edit routes, stops, stop spacing, headways, and service spans
- Measure population, jobs, schools, and essential services within walksheds
- Estimate fleet requirements and annualized service hours
- Compare access changes by neighborhood, ward, or custom district
- Export scenario reports as CSV and GeoJSON
- Role-based configuration for planners, reviewers, and administrators

## Install

### Requirements

- Node.js 20+
- PostgreSQL 15+
- PostGIS 3+
- Redis 7+
- GDAL 3.7+

### Setup

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

Create the database:

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

Copy the environment file and update local values:

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

Run migrations and seed reference data:

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

Start the application:

```bash
npm run dev
```

The planner 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 web app and select the imported feed from the project dashboard.

### Create a Scenario

1. Open a transit network project.
2. Select **New Scenario**.
3. Choose a base service period, such as `weekday`, `saturday`, or `sunday`.
4. Edit routes, stops, headways, or service spans.
5. Run the scenario analysis.
6. Compare results against the existing network.

### Export Results

```bash
npm run scenario:export -- --scenario spring-2027-draft --format geojson
```

Supported export formats:

- `csv`
- `geojson`
- `json`

## Configuration

Configuration is managed through environment variables.

| Variable | Description | Default |
| --- | --- | --- |
| `DATABASE_URL` | PostgreSQL connection string | `postgres://localhost/transit_planner` |
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |
| `APP_PORT` | Local application port | `3000` |
| `MAPBOX_TOKEN` | Mapbox access token for basemaps | Required |
| `DEFAULT_WALK_SPEED_KPH` | Walkshed calculation speed | `4.8` |
| `DEFAULT_WALKSHED_MINUTES` | Default access analysis threshold | `10` |
| `GTFS_IMPORT_STRICT` | Reject invalid GTFS records during import | `false` |
| `REPORT_TIMEZONE` | Timezone used in reports | `America/New_York` |

Example `.env`:

```env
DATABASE_URL=postgres://localhost/transit_planner
REDIS_URL=redis://localhost:6379
APP_PORT=3000
MAPBOX_TOKEN=your-mapbox-token
DEFAULT_WALK_SPEED_KPH=4.8
DEFAULT_WALKSHED_MINUTES=10
GTFS_IMPORT_STRICT=false
REPORT_TIMEZONE=America/New_York
```

## License

MIT