# Regional Bike Share

A production-oriented platform for operating a regional bike-sharing network across multiple cities, transit hubs, campuses, and partner locations.

Regional Bike Share provides station discovery, bike availability tracking, trip management, rider accounts, maintenance workflows, and operator reporting through a unified API and web dashboard.

## Overview

The system is designed for municipalities, mobility operators, and regional transit agencies that need to manage shared bicycles across a distributed service area.

It supports both docked and dockless fleets, real-time station status, rider subscriptions, trip billing, maintenance dispatching, and integration with third-party mobility apps through GBFS-compatible feeds.

## Features

- Real-time bike and dock availability by station
- Rider registration, authentication, and account management
- Trip start, pause, resume, and end workflows
- Pricing plans for casual riders, members, students, and partners
- Docked, dockless, e-bike, and adaptive bike support
- Maintenance tickets for damaged bikes, low batteries, and offline stations
- Operator dashboard for fleet balancing and service alerts
- Regional zones, service boundaries, and geofencing rules
- Payment provider integration for trip charges and subscriptions
- GBFS feed generation for public mobility data
- Admin roles for operators, mechanics, support agents, and city partners
- Audit logs for trips, payments, bike state changes, and admin actions

## Install

### Requirements

- Node.js 20+
- PostgreSQL 15+
- Redis 7+
- pnpm 9+

### Setup

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

Create a local environment file:

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

Run database migrations:

```bash
pnpm db:migrate
```

Seed local development data:

```bash
pnpm db:seed
```

Start the application:

```bash
pnpm dev
```

The API will be available at:

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

The operator dashboard will be available at:

```text
http://localhost:5173
```

## Usage

### Start a Development Environment

```bash
pnpm dev
```

### Run Tests

```bash
pnpm test
```

### Run Database Migrations

```bash
pnpm db:migrate
```

### Generate Public GBFS Feeds

```bash
pnpm gbfs:generate
```

### Create an Admin User

```bash
pnpm admin:create --email ops@example.org --role operator
```

### Example API Request

```bash
curl http://localhost:3000/api/stations
```

Example response:

```json
[
  {
    "id": "station_1027",
    "name": "Central Station East",
    "city": "Riverton",
    "available_bikes": 12,
    "available_docks": 8,
    "status": "active"
  }
]
```

## Configuration

Configuration is managed through environment variables.

| Variable | Description | Default |
| --- | --- | --- |
| `APP_ENV` | Application environment: `development`, `test`, or `production` | `development` |
| `API_PORT` | Port for the backend API | `3000` |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `REDIS_URL` | Redis connection string | Required |
| `JWT_SECRET` | Secret used to sign rider and admin tokens | Required |
| `PUBLIC_BASE_URL` | Public URL for generated links and callbacks | `http://localhost:3000` |
| `DASHBOARD_URL` | Operator dashboard URL | `http://localhost:5173` |
| `PAYMENT_PROVIDER` | Payment provider adapter: `stripe`, `adyen`, or `mock` | `mock` |
| `PAYMENT_API_KEY` | API key for the configured payment provider | Required in production |
| `GBFS_PUBLIC_URL` | Public base URL for GBFS feeds | Required in production |
| `DEFAULT_REGION` | Default operating region code | `metro` |
| `TRIP_MAX_DURATION_MINUTES` | Maximum allowed trip duration | `1440` |
| `LOW_BATTERY_THRESHOLD` | E-bike battery percentage that triggers maintenance | `20` |
| `ENABLE_DOCKLESS` | Enables dockless trip ending within service zones | `false` |
| `ENABLE_SMS_ALERTS` | Enables SMS notifications for riders and operators | `false` |

Example `.env`:

```env
APP_ENV=development
API_PORT=3000
DATABASE_URL=postgres://postgres:postgres@localhost:5432/bikeshare
REDIS_URL=redis://localhost:6379
JWT_SECRET=replace-this-in-production
PUBLIC_BASE_URL=http://localhost:3000
DASHBOARD_URL=http://localhost:5173
PAYMENT_PROVIDER=mock
DEFAULT_REGION=metro
TRIP_MAX_DURATION_MINUTES=1440
LOW_BATTERY_THRESHOLD=20
ENABLE_DOCKLESS=true
ENABLE_SMS_ALERTS=false
```

## License

MIT