Miniso México — Loyalty Integration Backend

The production integration backend of Miniso México's loyalty program, connecting the VTEX storefront, Aptos CRM and the mobile app.

Status
Implemented and deployed to production on CentOS 8, as a Corebiz project.
Stack
Node.js · Express · MongoDB · REST · VTEX · Aptos CRM · CentOS 8

At a glance

01Problem
Miniso México's loyalty program spans three systems: the VTEX storefront, Aptos CRM and a mobile app. Customers register and check their loyalty points from either channel, and each piece of data has to come from the system that owns it.
02My responsibility
I implemented and owned the production backend integration layer on my own, within a high-level architecture defined by my manager: the services connecting VTEX, Aptos CRM and the mobile app, plus persistence, recovery, reconciliation and reporting.
03Architectural challenge
VTEX owns customer registration and Aptos owns loyalty points, while registration through VTEX Master Data V1 could fail intermittently. The backend has to keep both flows moving without becoming a competing source of truth.
04Outcome
A production integration layer through which every registration and loyalty-point flow passed, with scheduled recovery, automatic and manual reconciliation, and business reporting.

Architecture

Three systems, one integration layer

  1. Channels

    • VTEX storefrontCustomer registration and loyalty-point queries
    • Mobile appCustomer registration and loyalty-point queries
  2. Integration layer

    • Integration backend · Node.js / ExpressEvery relevant flow passes through it. Deployed on CentOS 8.
      • Orchestrates registration and loyalty-point flows
      • Persists registration and transaction data (MongoDB)
      • Hourly recovery of pending operations
      • Automatic and manual reconciliation
      • Business and operational reporting
  3. Systems of record

    • VTEXSource of truth for customer registration
    • Aptos CRMSource of truth for loyalty points

Source of truth

Conceptual view, simplified. The backend keeps its own records for recovery, reconciliation and reporting, but never an authoritative point balance: when values differ, Aptos CRM prevails.

Architectural principle

Explicit sources of truth

The architecture, defined by my manager, gives each system one responsibility: VTEX is the source of truth for customer registration, and Aptos CRM is the source of truth for loyalty points. The backend I implemented orchestrates the flows and keeps its own records for recovery, reconciliation and reporting, but never an authoritative point balance. When point values differ, Aptos prevails.

Flows and operations

How registration and points move through the backend

Registration flow

  1. 01VTEX or mobile appThe customer registers
  2. 02Integration backendReceives and records the registration
  3. 03VTEX + Aptos CRMCustomer registration in VTEX; loyalty registration propagated to Aptos
RecoveryRecoverable failures are queued and reprocessed in hourly batches.
Registration originates in either channel and always passes through the backend. Highlighted: the systems of record.

Loyalty points flow

  1. 01VTEX or mobile appRequests loyalty information
  2. 02Integration backendQueries Aptos on the channel’s behalf
  3. 03Aptos CRMReturns the current points
  4. 04Integration backendRelays the response
  5. 05Requesting channelShows the current points
Points are always read from Aptos CRM, the source of truth (highlighted).
  1. Registration flow

    Registration starts in the VTEX storefront or in the mobile app and always passes through the backend. VTEX controls the customer registration, and the backend propagates the corresponding loyalty registration to Aptos CRM.

  2. Loyalty points flow

    When the storefront or the app asks for a customer's points, the backend queries Aptos CRM and returns the current value to the requesting channel. Points are read from Aptos, not from the backend's own data.

  3. Operational resilience

    Registration through VTEX Master Data V1 could fail intermittently. I implemented an hourly scheduled job that reprocesses pending registrations and operations in batches, with recoverable operations queued for a later run. Some errors came from outside the backend's control and could not be recovered automatically.

  4. Reconciliation

    The backend supports automatic and manual reconciliation of loyalty-related operations and data.

  5. Metrics and reporting

    Reporting requested by the Director of E-commerce, generated from the registration and transaction flows: registered users, users who activated their loyalty registration, registered users who did not, the selections made during registration, and transaction-related information.

For technical readers

Technical detail

Context

Miniso México's loyalty program, delivered as a Corebiz project. Customers register through the VTEX storefront or the mobile app and query their loyalty points from either channel. The backend is the integration layer between VTEX, Aptos CRM and the mobile app, and every relevant flow passes through it.

Responsibility

  • Implemented the production backend integration layer, working alone on the backend.
  • Built the services connecting VTEX, Aptos CRM and the mobile application, including the services the app consumes for registration and loyalty-point queries.
  • Implemented the persistence, synchronization, recovery, reconciliation and reporting flows.
  • The high-level architecture was defined by my manager; I owned its backend implementation.

Complexity

  • Three systems with different responsibilities, and two of them authoritative for different data.
  • Intermittent registration failures in VTEX Master Data V1, some of them outside the backend's control.
  • Two channels, storefront and mobile app, sharing the same registration and loyalty flows.

Architecture

  • REST services in Node.js and Express, consumed by the storefront and the mobile app.
  • MongoDB for backend-side data, including user-registration and transaction information. It does not hold the authoritative point balance.
  • An hourly scheduled job with a queue for recoverable operations, processed in batches.
  • Deployed and operated on CentOS 8.

Alternatives & trade-offs

  • Recovery runs on a schedule, so a recovered registration completes on a later hourly run rather than immediately.
  • Errors that originate outside the backend cannot be recovered automatically and need manual follow-up, which is what manual reconciliation is for.

Result

  • A single integration layer for registration and loyalty points across the storefront, the mobile app and Aptos CRM.
  • Clear ownership of data, with Aptos CRM as the authority for points and VTEX for customer registration.
  • Scheduled recovery of intermittent registration failures, plus automatic and manual reconciliation.
  • Business and operational reporting for the e-commerce leadership.