# Regional Bike Share Network

A backend service for operating a multi-city bike-sharing network. It tracks stations, bicycles, docks, trips, memberships, and maintenance events while exposing APIs for rider applications and operator dashboards.

## Features

- Real-time station, dock, and bicycle availability
- Support for standard bikes, e-bikes, and adaptive cycles
- Trip creation, completion, pricing, and history
- Membership plans and pay-as-you-go riders
- Regional service areas, time zones, and pricing rules
- Bicycle maintenance and inspection workflows
- Station capacity and rebalancing alerts
- REST API with health and readiness endpoints
- PostgreSQL persistence and Redis caching
- Docker-based local development

## Requirements

- Node.js 20 or later
- PostgreSQL 15 or later
- Redis 7 or later
- npm 10 or later

Docker Compose can provide PostgreSQL and Redis for local development.

## 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
```

Start the supporting services:

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

Run database migrations and load sample stations:

```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`.

## Usage

Check service health:

```bash
curl http://localhost:3000/health
```

List nearby stations:

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

Start a trip:

```bash
curl -X POST http://localhost:3000/api/v1/trips \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bikeId": "bike_2048",
    "startStationId": "station_union_square"
  }'
```

Complete a trip:

```bash
curl -X POST http://localhost:3000/api/v1/trips/trip_7f32/complete \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "endStationId": "station_waterfront"
  }'
```

Run the test suite:

```bash
npm test
```

Run linting and type checks:

```bash
npm run lint
npm run typecheck
```

## Configuration

Configuration is loaded from environment variables. Values in `.env` are intended for local development and should not be committed.

| Variable | Default | Description |
| --- | --- | --- |
| `NODE_ENV` | `development` | Runtime environment |
| `PORT` | `3000` | HTTP server port |
| `DATABASE_URL` | — | PostgreSQL connection string |
| `REDIS_URL` | `redis://localhost:6379` | Redis connection string |
| `JWT_SECRET` | — | Secret used to verify access tokens |
| `REGION_CODE` | `ca-gta` | Operator-defined regional identifier |
| `DEFAULT_TIMEZONE` | `America/Toronto` | Time zone for schedules and reports |
| `DEFAULT_CURRENCY` | `CAD` | ISO 4217 billing currency |
| `DEFAULT_SEARCH_RADIUS_METERS` | `3000` | Station search radius |
| `MAX_TRIP_DURATION_MINUTES` | `1440` | Maximum trip duration before review |
| `AVAILABILITY_CACHE_TTL_SECONDS` | `15` | Station availability cache lifetime |
| `REBALANCING_ALERT_THRESHOLD` | `0.15` | Empty/full station alert threshold |
| `LOG_LEVEL` | `info` | Application logging level |
| `CORS_ORIGINS` | `http://localhost:5173` | Comma-separated allowed origins |

Example `.env`:

```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
REGION_CODE=ca-gta
DEFAULT_TIMEZONE=America/Toronto
DEFAULT_CURRENCY=CAD
CORS_ORIGINS=http://localhost:5173
```

Pricing, service areas, and operating hours are defined in `config/regions.yml`:

```yaml
regions:
  ca-gta:
    name: Greater Toronto Area
    timezone: America/Toronto
    currency: CAD
    pricing:
      unlockFee: 1.00
      standardPerMinute: 0.15
      electricPerMinute: 0.30
    operatingHours:
      start: "05:00"
      end: "02:00"
```

Restart the service after changing environment variables or regional configuration.