Product service

The product service is the catalogue, and it holds more than a list of things for sale. It is where a product’s shape, its permissions and its lifecycle are all defined, which makes it the service most worth understanding before an integration.

It is control plane, deployed once in Singapore, read by every market.

Note

The wire surface is the standard’s. Resource paths, methods, status codes, the error model, pagination and idempotency are declared once in Conventions, and each module’s API page carries the operations over its entities. What is tenant-specific, the host and the scope names your credentials carry, is issued with those credentials, because it differs per tenant by design. See Tenancy and scopes.

Inside a product record

One read returns the whole definition, because a caller that has to make four calls to understand one product will cache the pieces inconsistently.

Items. A product item is the thing actually covered, and its type says what kind of thing. A trip policy covering one passenger has one item of type coveredPerson. A motor policy covering a vehicle and its driver has two items of different types. Coverage requests are built item by item against these definitions.

Attributes. Both the product and each item carry attribute definitions, which is how the catalogue extends without a schema change. A trip product declares that it expects a vehicle plate and a vehicle type; a covered person expects a role, a name and a phone number. The coverage service validates a submitted coverage against these definitions rather than against a hardcoded struct.

Permissions. The catalogue records which insurers may underwrite a product and which brokers may sell it. This is the data the routing decision is made against, and it is also why a coverage request naming a product the channel is not permitted to sell is rejected before anything is issued.

Lifecycle. A product declares its own statuses and the transitions permitted between them.

The lifecycle is data, not code

This is the design choice on this page most likely to surprise.

The coverage service does not contain a state machine. When a coverage’s status changes, the service loads the product, reads the statuses and transitions that product declares, and checks the requested move against them. A product with no declared statuses is not stateful and rejects status changes entirely.

So a trip product that goes pending, active, closed and a motor product with a different set are not two code paths. They are two rows of configuration. Adding a status to one product is a catalogue change, and it does not touch the service that enforces it.

The cost is that the lifecycle is not visible in the code, and a reader of the coverage service cannot tell you what states exist. The benefit is that adding a product does not require a deployment of the service that issues it, which on a platform whose whole thesis is repeatable distribution across markets is the trade worth making.

Insurers

The catalogue also answers which carriers are on the platform. Which one handles a given request is a different question and is not answered here: that is a routing decision made per product, channel and market, and it is described under the coverage service.