# Regional Bike Share

Regional Bike Share is an open-source platform for operating a bike-sharing network across multiple cities and transit districts. It provides real-time station availability, trip management, fleet operations, and system integrations through a unified API and web dashboard.

## Features

- Live bike and dock availability
- Support for traditional bikes and e-bikes
- Rider accounts, memberships, and trip history
- QR code and station-based rentals
- Multi-city service areas and pricing rules
- Operations dashboard for rebalancing and maintenance
- GBFS feeds for journey planners and public data portals
- Configurable payment and notification providers
- Role-based access for operators, technicians, and administrators

## Requirements

- Node.js 20 or later
- PostgreSQL 15 or later
- Redis 7 or later
- Docker and Docker Compose (recommended)

## Installation

Clone the repository and install the dependencies:

```bash
git clone https://github.com/example/regional-bike-share.git
cd regional-bike-share
npm install
```

Create a local environment file:

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

Start PostgreSQL and Redis with Docker:

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

Run the database migrations and load sample stations:

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

Start the application:

```bash
npm run dev
```

The rider application will be available at `http://localhost:3000`, and the operations dashboard at `http://localhost:3000/operations`.

## Usage

### Find nearby stations

```bash
curl "http://localhost:3000/api/v1/stations?lat=43.6532&lon=-79.3832&radius=1500"
```

### View station availability

```bash
curl "http://localhost:3000/api/v1/stations/STN-1042"
```

### Start a trip

Authenticated requests require a bearer token:

```bash
curl -X POST "http://localhost:3000/api/v1/trips" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bikeId": "BIKE-7821",
    "originStationId": "STN-1042"
  }'
```

### Run tests

```bash
npm test
```

### Build for production

```bash
npm run build
npm start
```

## Configuration

Configuration is loaded from environment variables in `.env`.

| Variable | Description | Default |
| --- | --- | --- |
| `PORT` | HTTP server port | `3000` |
| `NODE_ENV` | Runtime environment | `development` |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |
| `JWT_SECRET` | Secret used to sign access tokens | Required |
| `PUBLIC_BASE_URL` | Public application URL | `http://localhost:3000` |
| `DEFAULT_TIMEZONE` | Default IANA timezone for service areas | `America/Toronto` |
| `DEFAULT_CURRENCY` | ISO 4217 billing currency | `CAD` |
| `GBFS_ENABLED` | Enable public GBFS feeds | `true` |
| `GBFS_REFRESH_SECONDS` | Availability feed refresh interval | `30` |
| `PAYMENT_PROVIDER` | Payment integration (`stripe` or `mock`) | `mock` |
| `STRIPE_SECRET_KEY` | Stripe API secret key | Empty |
| `MAP_TILES_URL` | Tile server URL used by network maps | OpenStreetMap |
| `SMTP_URL` | SMTP connection URL for email notifications | Empty |
| `LOG_LEVEL` | Application logging level | `info` |

At minimum, production deployments must provide secure values for `DATABASE_URL` and `JWT_SECRET`. Payment credentials are required when `PAYMENT_PROVIDER` is set to `stripe`.

Service areas, fares, station capacity, and vehicle types are managed in `config/network.yml`:

```yaml
network:
  name: Lakeshore Bike Share
  timezone: America/Toronto
  currency: CAD

vehicleTypes:
  - id: classic
    electric: false
  - id: ebike
    electric: true

pricing:
  unlockFee: 1.00
  includedMinutes: 30
  additionalMinuteRate: 0.15
```

Restart the application after changing environment variables or network configuration.