# GBFS Feed Structure

This folder contains GBFS v3.0 compliant JSON files for the Bora bikesharing system (Viseu region, Portugal).

## System Overview - Platform 29 (Bora)

- **39 stations** across Viseu region municipalities
- **145 bikes** operational (5 in maintenance)
- **245 docks** total
- Station capacity: 5-10 docks per station
- Mix of docked and free-floating bikes

## Generated Files

- **gbfs.json** - Auto-discovery file (entry point)
- **system_information.json** - System metadata (static, TTL: 24h)
- **vehicle_types.json** - Vehicle type definitions (static, TTL: 24h)
- **station_information.json** - Station locations and details (semi-static, TTL: 1h)
- **station_status.json** - Real-time station availability (dynamic, TTL: 0s)
- **vehicle_status.json** - Free-floating bikes (dynamic, TTL: 0s)

## Data Transformation Pipeline

The GBFS feed is generated from Muve API using the following pipeline:

```bash
npm run gbfs  # Full pipeline with validation
```

Individual steps:
1. **Fetch** (`npm run fetch`) - Fetches live data from Muve API
2. **Compare** (`npm run compare`) - Validates data consistency
3. **Validate** (`npm run validate`) - Checks data integrity
4. **Transform** (`npm run transform`) - Generates GBFS files
5. **Validate GBFS** (`npm run validate:gbfs`) - Schema validation

## API Data Mapping

### station_information.json
**Source:** `GET /api/platform/29`, `GET /api/stations`, `GET /api/docks`

```
API Field → GBFS Field
------------------------
stations.id → station_id
stations.name → name[].text
stations.lat → lat
stations.lon → lon
stations.address → address
stations.internal_id → short_name
docks count → capacity
```

### station_status.json
**Source:** `GET /api/stations`, `GET /api/docks`, `GET /api/bikes`

- Matches bikes to stations via `docks.docked_bike_id` → `bikes.internal_id`
- Calculates available bikes and docks per station
- Real-time operational status

### vehicle_status.json
**Source:** `GET /api/bikes`

- Free-floating bikes (not docked)
- GPS coordinates and battery status
- Vehicle type and availability

### vehicle_types.json
**Generated:** Static configuration

- Defines "Bora Electric Bike" specifications
- Form factor: bicycle, electric assist
- Max range: 50km

## Important Notes

1. **Security**: Sensitive Stripe API keys are automatically removed during fetch
2. **Timestamps**: All timestamps are in RFC3339 format (ISO 8601)
3. **Privacy**: Vehicle IDs are stable (`bike_{id}`) but don't expose user data
4. **Updates**: Run `npm run gbfs` every 10 minutes via cron for real-time data
5. **HTTPS**: All feeds must be served over HTTPS

## Deployment

The feed is deployed at: `https://gbfs.primelayer.pt/`

**Cron job example** (every 10 minutes):
```bash
*/10 * * * * cd /path/to/gbfs-smartmobility && npm run gbfs >> /var/log/gbfs-cron.log 2>&1
```

## Registration

Register the feed at: https://github.com/MobilityData/gbfs/blob/master/systems.csv