The Eclipse Architecture

Eclipse is an API-first SAAS hosted on AWS by Ukheshe. At the simplest level, it’s a set of 250+ restful endpoints all carefully designed to provide a consistent, powerful yet simple set of services covering everything from customer onboarding, to wallets, card issuing and payments. Eclipse has an admin portal that consumes the API’s for Adhoc, CRM and general administration tasks. The intent however is that most tenants of Eclipse would utilise their own branded customer-facing channels, and those would in turn call Eclipse directly or via their own backend servers. Accompanying the admin portal and API’s are a set of white label starting points for tenants interested in building channels on top of Eclipse (or having Ukheshe build channels for them):

A white label WhatsApp bot covering all the core functionality of onboarding, wallets, card issuing, QR payments and VAS
A white label React-based PWA covering all the core functionality of onboarding, wallets, card issuing, QR payments and VAS
A white label React native based App covering all the core functionality of onboarding, wallets, card issuing, QR payments and VAS

The combination of the white label channels and Eclipse API allows tenants to go to market quickly and evolve their proposition.

The Restful API’s exposed by Eclipse all point to the same URL for all tenants. In the URL’s there is a path parameter that determines the tenant calling the API and this is also enforced by the JWT bearer token passed on each API request. As an example, tenant 100 could get a list of their customers with a GET request to:

https://ukheshe.live/eclipse-conductor/rest/v1/tenants/100/customers

Whereas tenant 200 would use:

https://ukheshe.live/eclipse-conductor/rest/v1/tenants/200/customers

Tenants are logically separated on the backend. Each has its own configuration, own customers, own wallets etc but shares the underlying AWS compute and persistence services. This is similar to Office365 or Google Apps - an organisation has their own settings and environment but all are hosted across a farm of underlying shared infrastructure.

The Eclipse backend is layered, utilising best-of-breed components in the various layers to provide a modern scalable cloud-native architecture. These layers are built up as follows:

AWS Data Center infrastructure (compute, storage and networking)
AWS Elastic container services for container-based deployments, autoscaling and resilience
AWS Relational database services and document database services for data persistence
Docker-based containers using Linux as a base
Java 19 runtime
Quarkus framework
Numerous open-source libraries
Ukheshe standardised architecture libraries
Eclipse business logic code

The high-level architecture is depicted in the following diagram:

Ukheshe, as part of the AWS partner programme, went through an architecture and security audit with AWS to ensure that the overall architecture followed best practices and recommendations for scalability, resistance and security. The Eclipse platform was given the Amazon "AWS Well Architected" stamp of approval. In addition to this, the Eclipse platform has had a 100% uptime over the last 24 months, and less than 30s of downtime since inception. There have been zero security exploits.

Although Eclipse as a whole serves as an orchestration layer providing coarse-grained APIs hiding the complexity of multiple complex fine-grained APIs, it is a lot more than simply an ESB or API gateway. Many of the core constructs in Eclipse are implemented as microservices and have state and persistence (e.g. customers, wallets etc.). The API’s and microservices are designed in such a way that implementations can be externalized or hosted internally in Eclipse. E.g. a wallet’s Store of value could sit in Eclipse using its wallet functionality, or point to an external store of value such as a bank account, crypto platform or card management system. The Eclipse API remains consistent and yet the implementation behind it can evolve or change. A good example is card issuing - the API calls on Eclipse to issue a card to a customer are very simple - as few as one or 2 fields in a POST of JSON and a card is issued. The backend card management system could be Mastercard PTS or a Postilion postbridge interface or anything in between - and yet none of this is the concern of the API caller.

One of the core technology enablers in Eclipse is the component known as the eclipse-conductor. This is the entry point for all API calls. The conductor covers many of the functional blocks seen in a combination of an API gateway and ESB and was built by Ukheshe to satisfy the use cases of Eclipse and overcomes many of the issues the team has faced using off the shelf API gateways and ESB’s that require numerous components and typically awkward composition logic languages such as BPEL or Lua scripting. The conductor is built on top of Vert.X/Quarkus using a completely stateless non-blocking IO model for huge scalability and performance and allows for orchestration logic to sit in Java. The core functional capabilities are as follows:

Identity provider / Authentication server supporting JWT, OIDC, SAML2 and custom auth schemes
API tracing
API metrics (latency, error rates, concurrency etc.)
Load balancing & failover
Java based service composition logic
Reverse proxy
Service discovery
Data validation
Caching
Authorization logic & policy enforcement
Web application firewall (XSS, SQL injection)
Accounting
Rate limiting (throughput and concurrency)
TLS termination

The Eclipse conductor either proxies to or orchestrates across downstream microservices which again are largely built using Java/Quarkus.

In order to best understand the API’s and their functionality, its key to cover the various names and conventions used in this document along with the Swagger