carpool-service/README.md

# COOPGO Carpool Service

COOPGO Carpool Service is a carpool management microservice. It is part of the COOPGO Technical Platform and the base carpool component of COOPGO's [RIDYGO](https://ridygo.fr) application. It was redesigned from scratch to implement natively the new OCSS carpool standard and bring interoperability.

This is not a full featured carpooling application. There is no UI and it only implements basic carpooling functionalities (create, search, book journeys). The objective of this service is to be embedded in a bigger carpool or Mobility as a Service platform.

It provides a gRPC service to interact with other microservices or the main application, and an HTTP API to provide interoperability with external carpooling operators.

## Technical architecture

### Managing trips and journeys 

Trips and journeys are managed through the provided gRPC service and stored in the database (PostgreSQL or MongoDB for the moment). They are stored in the database as GeoJSON feature collections with extra members defining the trips and journeys non-geographical parameters.

Many thanks to [https://github.com/paulmach/orb](https://github.com/paulmach/orb) !

### Tiles architecture

To reduce dependencies on the chosen database, we decided to manage geographical calculations directly in our code instead of relying completely on MongoDB or PostgreSQL/Postgis geographical features.

We use a tiles system to retrieve relevant journeys easily. Each tile is defined by :

- driver or passenger status of the journey
- date of the journey
- Tile ID in the tiles grid. The tiles grid is inspired by Valhalla https://github.com/Telenav/open-source-spec/blob/master/valhalla/doc/valhalla-tiles-basic.md. We use a level 0 grid.

Tile IDs from each journey/trip is processed at creation time and stored with the journeys or regular trips in the database.

We can simply generate tiles by retrieving the appropriate data from the database.

### Search 

Search is handled by generating the appropriate tiles for the fiven departure/destination/date/driver/passenger state, and filter the journeys included in these tiles.

TODO : Performance could probably be improved by parallelilizing the filtering flow with goroutines, and adding some tiles caching with [groupcache](https://github.com/golang/groupcache)

## Database

Supported databases :

- [x] PostgreSQL
- [x] MongoDB

TODO : add the option for a simple embedded key-value store like [bbolt](https://github.com/etcd-io/bbolt) or [badgerdb](https://github.com/dgraph-io/badger), with a distributed consensus mechanism (like [raft](https://github.com/hashicorp/raft)) to allow for even simpler deployments when the overall infrastructure doesn't use PostgreSQL or MongoDB

## OCSS standard

The OCSS standard is the new carpooling interoperability standard defined by the french carpooling ecosystem.

COOPGO Carpool Service intends to support this standard completely. 

State of the implementation :

- Server side :
  - [x] GET `/driver_journeys`
  - [x] GET `/passenger_journeys`
  - [ ] GET `/driver_regular_trips`
  - [ ] GET `/passenger_regular_trips`
  - [x] POST `/bookings`
  - [x] PATCH `/bookings`
  - [x] GET `/bookings`
  - [ ] GET `/messages`
  - [x] GET `/status`
- Client side : ongoing

## Licence

COOPGO Carpool Service is released under the terms of the AGPL version 3 licence