Skip to main content

README

External verification and activation (EVA):

For more information about EVA you can check out these pages​

This is the architectural documentation for External Verification and Activation(EVA) against 3rd parties service providers to verify and activate deposits, vouchers and items.

Deposit is part of MVP scope and designed accordingly.

The following Confluence pages are also part of the system documentation.

IDEALS architecture​

Interface segregation​

Ingestor APIs to EVA will be divided using capabilities:

  1. Deposit API - (without provision of additional inputs, it is simpler case where request is responded straightaway)
  2. Voucher API - (with additional inputs, more complex case then Deposit API where THIRD PARTY PROVIDER demands more info or can add tender to it.)
  3. Items API
  4. Other capabilities (new THIRD PARTY PROVIDER onboarding, to be added in future)

Current scope supports following RESTful APIs (JSON) towards external systems:

  1. Business configuration API - The RESTFul API with CRUD operations to maintain business configuration used by integration service.
  2. Deposit API - To receive messages from POS channels and publish to respective Pubsub topics at EVA. We will use Pubsub Ingestor for such API/s. In future, similar setup would be done for Voucher and Items API too.
  3. Response interconnect - supports non-GCP deployed checkout with response JSON message.
  • Business configuration exposes OpenAPI schema which serves GET requests from POS channels.
  • APIs (Deposit, vouchers, Items etc) expose OpenAPIs schema which accept message payloads from POS channels and publish messages onto PubSub.
  • The THIRD_PARTY_ROUTER service receives messages over HTTP from PubSub.
  • THRID_PARTY_INVOKER receives messages over HTTP from THIRD_PARTY_ROUTER routers.
  • non-GCP deployed checkouts responses are persisted into Firestore
  • GCP deployed checkouts responses are written directly to GCP deployed checkouts PubSub Topic.
  • POS response interconnect service responds to requests from non-GCP deployed checkouts over HTTP.
  • Cloud Scheduler job will clean up reponse payloads from firestore db after business hours everyday.

Availability over consistency​

The solution is event-driven and eventually consistent. The system will receive all scan messages and forward those at least once or send them to a dead letter queue. Messages are delivered as soon as possible, but with no hard time constraint.

The system is designed to be available even as parts of the systems are failing. Its event-driven architecture also means it will continue to process messages and catch up after partial outages.

Loose-coupling​

  • Database is only manipulated from one service. Business configurations are read by multiple services.
  • External communication is kept loose via versioned OpenAPI schemas or via PubSub.
  • All components use message-passing and are therefore not strictly tied to each other.

Single responsibility​

  • The system as a whole does one thing only: request-response towards external service providers.
  • Each individual service has a single responsibility.

Correlation-Id​

  • All requests (&response) will have a unique correlation-id provided by POS channels.
  • Use Correlation-ID as primary key while defining tracing metrics.

Multi-tenancy​

  • The solution is generic and multi-tenant friendly i.e. multiple POS channels (GCP and non-GCP deployed checkouts) & THIRD PARTY PROVIDERS providers can be integrated(added\removed) without disturbing existing services.
  • Request/response & Business configuration will carry tenant-id
  • Tetant-ID to be utilized for analytical purposes i.e. how many requests per tenant.

Auditing​

  • We will log necessary information against all statuses(2XX, 4XX, 5XX) to GCP's Operations with Correlation-ID/Tenant-ID.

Security​

Internal (within GCP)​

  • Communication within micro services would use service accounts (GCP IAM) following least privilege principles i.e. giving minimal roles to service accounts for required jobs/actions.

External (outside)​

  • Ingress & egress (endpoints between POS and Integration service) are secured by using OCMS.
  • Egress traffic will utilize THIRD PARTY PROVIDERS authentication methods e.g. JWT tokens for JSON API(e.g. for ICA) or username & password for SOAP API (ie for TOMRA). GCP secret manager will be used for THIRD PARTY PROVIDERS credentials management.
  • This service does not persist any personal identifiable information - out of GDPR purview. Note: However, it may be revisited for new THIRD PARTY PROVIDER onboarding (based on requirement of course).

Data mesh​

  • No plan to build a data mesh for MVP.

    Note: Possibility to use Cloud Storage to archive a completed request for dispute resolution, analytical purposes to extract useful metrics for the tenants. It could be part of future upgrades/enhancements.

Global reach​

  • Not applicable for MVP (limited to SE).
  • Moreover, Integration service depends on regional service providers so it will be deployed in the closest region (europe-west1 ). For global reach, it needs to be deployed in multiple regions.

Internationalization​

  • Translation of status response (success/failures) message from English to Local language is included.
  • Response text will be THIRD PARTY PROVIDERS dependent, they can return responses in English or any other language. In such a case, the Integration Service should translate it according to the consumer's needs. (Generally all THIRD PARTY PROVIDERS should use English for status messages, not mandatory though!) Note: TOMRA will return status text in english only.

Solution design​

Constraints​

  • All messages must include barcode data and THIRD PARTY PROVIDERS identifiers (e.g. tenant-id, Correlation-ID, Provider-ID) attributes.
  • All messages to be relayed must be published to a PubSub topic.
  • Business logic in each THIRD_PARTY_INVOKER_ will be THIRD PARTY PROVIDERS provider dependent i.e. which API is used e.g. JSON or SOAP. Business logic will shape up accordingly. For TOMRA, it is a SOAP based API.

Technical implementation​

Solution evolution​

APIs will be defined based on capabilities. Solution will enhanced by developing following APIs along with new THIRD PARTY PROVIDERS onboarding changes:

  1. Business configuration API
  2. Deposit API
  3. Voucher API
  4. Item API

API Data Models & Specifications​

Note: All data models are subject to enhancement for betterment.

1. Business configuration API (JSON)​

This service provides business configurations for service providers i.e. barcode specifications, blocked prefixes, THIRD PARTY PROVIDERS filter conditions.