Handbook

Cloud Applications

At the highest level, the application layer is divided into microservice applications, front-end applications and data applications.

Microservice Applications

These applications implement by far the bulk of the business logic of the mx51 platform. They are written in the Go programming language by the backend chapter. gRPC is used for request/response-type communication between microservices. A message queue publisher/consumer pattern is used where asynchronicity is required. Some services store state in PostgreSQL, cloud file storage, and/or Redis. Redis is also used to facilitate end-to-end real-time notifications, for example from the device gateway to the BFF and vice versa.

External Microservices

Some microservices sit on the edge of the platform and serve the outside world via web APIs that are defined using OpenAPI and Postman.

Some of these external microservices are classic APIs that serve third parties and hence have a published specification. Other external microservices are built to serve the platform’s own front-end applications, and are sometimes referred to as BFFs (backend for frontend).

External microservices are mostly stateless and invoke internal microservices for business logic. They adapt incoming requests from the external protocol and model to the internal protocol and model. Most importantly, they are responsible for doing authentication of requests by leveraging middleware supplied by the user-service.

One special external microservice is the Device Gateway. The MXAs running on payment terminals connect to the device gateway to access the platform. Devices have their own way of authenticating with the platform.

Noteworthy external microservices:

  • Merchant Dashboard BFF – API used by the Merchant Dashboard Front-end
  • Support Dashboard BFF – API used by the Support Dashboard Front-end
  • Tenant API – Used by the Tenant to provision and update merchant information in their mx51 tenancy
  • In-Store Merchant API – Used by merchants to automate against instead of using the merchant dashboard manually
  • Device Gateway – What the MXA running on the payment terminals connects to

Internal Microservices

Internal microservices implement the bulk of the business logic.

A stateful microservice owns a tightly coupled part of the domain model and abstracts it behind endpoints defined using protocol buffers and served using gRPC.

Some internal microservices also act as workers (sometimes also called consumers) pulling tasks from queues.

Noteworthy internal microservices responsibilities:

  • User – Owns authentication, authorization and session management for dashboard users and API keys
  • Org – Owns the merchant domain model
  • Transaction – Owns financial transactions and payment executions
  • Device – Owns the payment device domain model and the registration/authentication for RTM
  • Crypto – Helps other services to do application-level encryption using a DEK-KEK pattern
  • Tokenization – PCI card data tokenization, stores encrypted card data
  • Message – Makes it easy for other services to send out emails and SMS

When and How to Design a New Microservice

The right granularity for a microservice is not always obvious. A microservice owns a tightly coupled part of the domain model. If it’s too small, it will not return on investment, while if it does too many disparate functions, it will not scale effectively.

A good example of when a new microservice was rightly designed and built was the Dispute Service for the disputes functionality. It was clearly a brand new vertical in the domain model. It was not tightly coupled to other parts, and not every tenant would have it turned on.

Another good example of the right granularity for a horizontal need is the Crypto Service and similarly the Message Service.

An example of when the wrong granularity was originally chosen, and then fixed later with hindsight, was the Transaction Service and the Payment Service, which were later combined because they were actually tightly coupled.

It is always advised to design on paper for more than what needs to be initially delivered, but then build just enough in the right direction to go to market. The design is approached in a domain driven manner, obtaining as much foresight as possible from the product and commercial teams. Design of new components or capabilities is not rushed and takes various iterations of refinements and clarifications. Care is taken when naming components, entities, attributes and endpoints so that the right terminology is reflected from the real life through the user interface, APIs and all the way through to the database schemas.

Front-End Applications

Front-end applications run in the user’s web browser. They are typically made up of HTML, JavaScript, CSS and media assets that are served by the cloud infrastructure over the internet.

Merchant Dashboard

The merchant dashboard is where users representing a merchant organisation log in to self-serve various functions such as listing transactions and configuring payments. It is owned by the Self-Serve squad.

It is a single-page application (SPA) written primarily in Angular. It talks to the back-end using its dedicated BFF. The merchant dashboard is branded for each tenant using a home-built user interface component framework.

The merchant dashboard is sometimes also referred to as the Merchant Portal.

Support Dashboard

The support dashboard is used by mx51 and the tenant’s own employees to help with supporting the merchants as well as to tweak tenancy configuration.

It is a single-page application (SPA) written primarily in Angular. It talks to the back-end using its dedicated BFF.

It is owned by the Self-Serve squad.

Online Payments Front-Ends

The e-commerce product offering is part of the mx51 platform. Its self-standing front-end components include:

  • PCI Hosted Fields – Can be embedded as HTML iframes on a third-party website to reduce PCI compliance
  • Drop-In UI – Can be embedded in the checkout process of third-party e-commerce websites to accept various forms of payments
  • Hosted Payment Page – A self-standing web-page for payments, typically redirected to from third-party e-commerce websites

These components are owned by the Online Payments squad and are built using a mix of programming frameworks.

Data Applications

mx51 continues to add data applications to the product offering. It started for internal use and is now being exposed to tenants themselves and perhaps to merchants in the future.

The Data & ML team owns this technical sector of the platform, and is supported by the cloud infrastructure team.

Snowflake is the technical centrepiece around which the data product is built.