# Regional Bike Share

A unified platform for operating a bike-sharing network across multiple cities and transit districts. Regional Bike Share provides riders with real-time station availability, trip planning, and account management while giving operators the tools to monitor fleets, rebalance bikes, and manage pricing.

## Features

- Real-time bike and dock availability
- Support for standard bikes, e-bikes, and adaptive cycles
- Station and service-area search
- Trip history, receipts, and membership management
- Regional passes and city-specific pricing rules
- Fleet health and battery monitoring
- Rebalancing alerts for operations teams
- GBFS-compatible public data feeds
- Multi-language and multi-time-zone support
- REST API with role-based access control

## Requirements

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

## Installation

Clone the repository and install 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
```

Initialize the database:

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

Start the development server:

```bash
npm run dev
```

The API is available at `http://localhost:3000`, and the rider application is available at `http://localhost:5173`.

### Docker

To start the application with PostgreSQL and Redis:

```bash
docker compose up --build
```

Run migrations in the application container:

```bash
docker compose exec api npm run db:migrate
```

## Usage

### Find nearby stations

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

### Check station availability

```bash
curl "http://localhost:3000/api/v1/stations/central-station/availability"
```

Example response:

```json
{
  "stationId": "central-station",
  "updatedAt": "2026-08-01T14:32:10Z",
  "bikes": {
    "standard": 8,
    "electric": 4,
    "adaptive": 1
  },
  "docksAvailable": 12
}
```

### Run common tasks

```bash
npm run dev          # Start development services
npm run build        # Create production builds
npm test             # Run the test suite
npm run lint         # Check code style
npm run db:migrate   # Apply database migrations
npm run worker       # Start background jobs
```

## Configuration

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

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `NODE_ENV` | No | `development` | Runtime environment |
| `PORT` | No | `3000` | API server port |
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
| `REDIS_URL` | Yes | — | Redis connection string |
| `JWT_SECRET` | Yes | — | Secret used to sign access tokens |
| `PUBLIC_APP_URL` | Yes | — | Public URL of the rider application |
| `DEFAULT_REGION` | No | `central` | Region used when none is specified |
| `DEFAULT_TIMEZONE` | No | `America/Toronto` | Time zone for schedules and reports |
| `GBFS_BASE_URL` | No | `/gbfs/v3` | Base path for public GBFS feeds |
| `MAP_PROVIDER` | No | `openstreetmap` | Map and geocoding provider |
| `MAP_API_KEY` | Conditional | — | API key for providers that require one |
| `TRIP_GRACE_PERIOD_SECONDS` | No | `60` | Time before trip billing begins |
| `E_BIKE_SURCHARGE_CENTS` | No | `100` | Default e-bike surcharge per trip |
| `LOG_LEVEL` | No | `info` | Application logging level |

Example:

```dotenv
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://bike_share:bike_share@localhost:5432/bike_share
REDIS_URL=redis://localhost:6379
JWT_SECRET=replace-with-a-long-random-value
PUBLIC_APP_URL=http://localhost:5173
DEFAULT_REGION=central
DEFAULT_TIMEZONE=America/Toronto
MAP_PROVIDER=openstreetmap
LOG_LEVEL=debug
```

Region-specific settings are stored in `config/regions.yml`:

```yaml
regions:
  central:
    name: Central District
    timezone: America/Toronto
    currency: CAD
    service_area: central.geojson
    pricing:
      unlock_cents: 100
      standard_per_minute_cents: 15
      electric_per_minute_cents: 30
```

Restart the API and background workers after changing environment variables or regional configuration.