Skip to main content

Introduction

randevu exposes a set of GraphQL services.

An example of an GraphQL service would be:

Query Endpoint
type Query {  getSupplyTypes: [SupplyType!]}

Services are making use of data types, like SupplyType (TODO: add link to SupplyType page) in this example:

Data Type Definition: SupplyType
type SupplyType {  id: ID!  name: String!  auto_backoffice_approval: Boolean  fields: [FieldType]!}

More details on concrete APIs in one of the following sections:

  • Marketplace API
  • Backoffice API

GraphQL schema underlying the whole randevu API is based on a high-level domain model, shown in the next section while all the particular details on concrete types are explained in context of APIs in the Schema section.

Domain model#

Domain model is a conceptual model that forms a layer of abstraction on the top of randevu features and randevu GraphQL schema. Only the most relavant concepts are shown and explained in this section.

domain model and API

It is highly recommended to go through this section before diving into randevu API details. Understanding this high-level perspective accelerates the understanding of the API itself.

Within this section, some references to API documentation are made. This is an example of a reference to the GraphQL type describing a SupplyType.

Business transactions and Flows#

Platforms are all about interaction between its participants.

Consumers will typically discover Supply or make orders for services they need. They will also make payments.

Providers might want to launch Auctions to attract more consumers to their Supply.

Both providers and consumers will interact, approve transactions or decline them, exchange information, etc.

Business transactions

Transactions in randevu are a high-level concept for definition of the value added transactions implmented and offered on the platform. Transactions will always involve 2 or more platform participants.

Some examples might be:

  • purchasing process with shopping cart
  • booking a Room
  • matching process on a dating app

See TransactionType for API level definition of the concept.

Following diagram shows the essential randevu concepts for handling transactions.

Flows types are low-level technical concept and randevu's implementation of generic state machine. It defined the states and transitions, as well as the rules governing all the state changes. Flows are nothing more than Flow type's instances on live marketplace.

Transaction types are business level definition of a participant facing interactive business process. Each Transaction type is linked to a Flow type which is effectively implementing the behavior. Transaction is an instance of its type on live marketplace and it natually also has its associated Flow.

Generic flows

Flows have a wide usage in randevu. Business transactions are only one application. As very generic state machines, Flows can also have different purpose, such as:

  • platform participants onboarding process
  • supply onboarding process
  • background processing jobs
  • etc.

See FlowType for API level definition of the concept.

Structural building blocks#

The following diagram depicts the essential randevu structural features: types and their mutual relationships.

Types in randevu

Types in randevu form the configuration of a marketplace. Types are definitions of real-world objects on the marketplace. randevu types are configured using the Backoffice.

Example: If a marketplace has Buyers and Sellers, use Backoffice to create two MarketplaceUserTypes - a Buyer and a Seller.

There are many schema types in randevu that contain the word "type" (e.g. MarketplaceUserType, SupplyType, etc).

  • MarketplaceUserType (also called ParticipantType) is a definition of a participant on a marketplace. It contains all the features needed to precisely define the structure and behavior of this marketplace users. A marketplace can have many participant types, but it typically starts with two.

  • SupplyType (also called ListingType) is a definition of whatever is transacted on this marketplace. It can be a product, a service, a bus ticket, a ride, etc. A marketplace can have many supply types, but it typically starts with one only.

  • MatchType is the central randevu abstraction. It defines all the aspects of a certain discovery-matching process, like discovery style, matching algorithm, approval methods, etc. As shown on the diagram, each MatchType defines a provider, consumer and a supply type. A marketplace can have many match types, but it typically starts with only one.

note

MatchType is kind of representation of the network effect in randevu. Multiple match types can be configured to support multiple network effects.

Building blocks and field types#

Field types are a mechanism of defining the structure of randevu building blocks. All randevu types explained in the previous section will typically incorporate several field types, to depict their own main features, such as: name, address, profile image, birth_place, etc.

FieldType can be seen an abstraction of a piece of data: a text, number, document... Each FieldType has a so called input_type, to define the valid values for it. Many input types are supported by randevu.

Field types can be added, removed, reordered, etc. Based on the field types, a concrete data will be entered in the system.

Types and objects#

Objects are instances of types in randevu. Based on a single type (e.g. MarketplaceUserType), many instances can be created, all sharing the same structure, defined by a originating type.

When a marketplace object is created (e.g. a real user has signed up on the marketplace), a type definition is used to create a real object with real (e.g. a concrete marketplace User).

Objects and fields#

Just like randevu types have FieldTypes, randevu object have Fields. For each FieldType defined in the originating type, a concrete Field will be created on the corresponding object, ready to accept the corresponding values (e.g. for the email, password, first and last name, etc.)

Wrapping it up#

After introducing all the main elements of randevu domain, in this section an example is shown.

The following diagram depicts the object created during a fictitious business transaction, let's say an Auction.

  • When a MatchingTool of a type Auction is created by the Seller participant, a Flow is triggered, which in turn creates a fresh business transaction to handle this particular Auction.

  • Each Buyer participant that decides to participate will be able to create a Match to place their offer.

  • Seller participant can review all offers and accept the best one.

note

Flows and Transactions are operating like wrappers around the randevu basic building blocks. They define the valid state the process can be in, rules on how to make transitions between the states, as well as all the actions that should be performed on the contained building blocks in otder to make progress with the transaction.