# CivicRoute Planner

CivicRoute Planner is a municipal transit planning service for trip discovery, route evaluation, and service-impact analysis. It combines GTFS schedules, stop accessibility metadata, walking transfers, and real-time service alerts to help riders and planners compare route options across bus, rail, tram, ferry, and paratransit services.

## Features

- Multimodal trip planning with walking, transfers, and scheduled transit
- GTFS import for agencies, routes, stops, trips, calendars, and stop times
- Real-time alert ingestion for delays, closures, detours, and cancellations
- Accessibility-aware routing using stop, vehicle, and transfer constraints
- Configurable walking speed, transfer buffers, service windows, and fare rules
- Planner API for public web, kiosk, and mobile integrations
- Administrative tools for validating feeds and inspecting route coverage
- Docker-based local development setup

## Install

### Requirements

- Node.js 20+
- PostgreSQL 15+
- Redis 7+
- Docker and Docker Compose

### Local setup

```bash
git clone https://github.com/example/civicroute-planner.git
cd civicroute-planner
npm install
cp .env.example .env
```

Start supporting services:

```bash
docker compose up -d postgres redis
```

Run database migrations:

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

Import a GTFS feed:

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

Start the application:

```bash
npm run dev
```

The API will be available at:

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

## Usage

### Plan a trip

```bash
curl "http://localhost:3000/api/v1/trips?from=43.6532,-79.3832&to=43.6426,-79.3871&departAt=2026-07-11T08:30:00-04:00"
```

### Validate a GTFS feed

```bash
npm run gtfs:validate -- ./data/agency-feed.zip
```

### Rebuild the routing index

```bash
npm run planner:rebuild-index
```

### Run tests

```bash
npm test
```

## Configuration

Configuration is read from environment variables. Copy `.env.example` to `.env` and update values for your municipality or deployment environment.

| Variable | Description | Default |
| --- | --- | --- |
| `PORT` | HTTP server port | `3000` |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |
| `GTFS_TIMEZONE` | Primary agency timezone | `America/Toronto` |
| `GTFS_IMPORT_PATH` | Default GTFS feed path | `./data/agency-feed.zip` |
| `WALKING_SPEED_MPS` | Walking speed used for access and transfers | `1.25` |
| `MAX_WALKING_DISTANCE_M` | Maximum walking distance for trip planning | `1200` |
| `TRANSFER_BUFFER_SECONDS` | Minimum transfer buffer between services | `180` |
| `SERVICE_ALERTS_URL` | GTFS-RT service alerts endpoint | Optional |
| `TRIP_UPDATES_URL` | GTFS-RT trip updates endpoint | Optional |
| `VEHICLE_POSITIONS_URL` | GTFS-RT vehicle positions endpoint | Optional |
| `ENABLE_ACCESSIBILITY_ROUTING` | Enable wheelchair and step-free constraints | `true` |
| `LOG_LEVEL` | Application log level | `info` |

Example:

```env
PORT=3000
DATABASE_URL=postgres://planner:planner@localhost:5432/civicroute
REDIS_URL=redis://localhost:6379
GTFS_TIMEZONE=America/Toronto
WALKING_SPEED_MPS=1.25
MAX_WALKING_DISTANCE_M=1200
TRANSFER_BUFFER_SECONDS=180
ENABLE_ACCESSIBILITY_ROUTING=true
LOG_LEVEL=info
```

For production deployments, set explicit database credentials, configure HTTPS at the reverse proxy, and schedule GTFS imports to match the agency feed publication cycle.