Introduction
randevu exposes a set of GraphQL services.
An example of an GraphQL service would be:
type Query { getSupplyTypes: [SupplyType!]}
Services are making use of data types, like SupplyType
(TODO: add link to SupplyType page) in this example:
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 modelDomain 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 FlowsPlatforms 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 blocksThe 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 calledParticipantType
) 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 calledListingType
) 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, eachMatchType
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.
MatchingToolType
is attached to aMatchType
and it defines the way aMatch
instance can be created from thatMatchType
. There are several available types of matching tools.
#
Building blocks and field typesField 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 objectsObjects 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 fieldsJust like randevu types have FieldType
s, randevu object have Field
s. 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 upAfter 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.