Loyalty — integration specification

Status: POC · Date: 2026-09-22 · Service: mock-loyalty-api (stands in for GalaxyJoy / SkyJoy)

Loyalty enriches; it never gates. When the loyalty system is down passengers still get online at the baseline — they lose the tier benefit, not the connection. This is the core difference from HR.

1. Why this is not HR

Two systems, two entirely different failure semantics. Confusing them is a serious defect.

Put plainly: a marketing system having a bad afternoon must not take a cabin offline.

For that reason loyalty.js and HrVerificationClient are separate classes with no shared helper — so nobody copy-pastes one's failure semantics onto the other by accident.

2. Where it sits

Portal → Keycloak            authenticate, obtain identity
       → Entitlement
            → Loyalty        what tier is this member?   ← customers only
            → DMN            what do the rules say?
       → Session             open the network

Loyalty feeds Entitlement, not Galaxy ID. Galaxy ID is the identity layer (ADR-002); benefits belong to Entitlement (ADR-005). The Flow 1 diagram currently draws this arrow the other way — see docs/03-architecture/FLOW1-AUTHEN-REVIEW.md §2.4.

Employees are not sent to loyalty. Their entitlement comes from HR verification; asking loyalty as well adds a dependency for nothing.

3. API

POST /api/v1/members/lookup

POST http://localhost:3006/api/v1/members/lookup
Content-Type: application/json
X-API-Key: {LOYALTY_API_KEY}
X-Correlation-ID: corr-...

{ "email": "an.nguyen@example.test" }

A member:

{
  "found": true,
  "memberRef": "GJ-000101",
  "tier": "GOLD",
  "status": "ACTIVE",
  "wifiBenefit": true
}

Not a member — a perfectly ordinary answer, not an error. Most passengers on any flight land here:

{ "found": false }

Minimal disclosure

Five fields, and no more. No name, phone, address, point balance, transaction history or date of birth.

A Wi-Fi portal needs a verdict, not a customer profile. A leak then costs little. An automated test rejects any additional field.

Tier is flattened when the account is not active

A SUSPENDED or CLOSED account keeps its historical tier inside the loyalty system, but this API returns tier: "NONE".

The reason: a consumer cannot then accidentally honour a tier the account no longer earns. That decision belongs at the source, not inferred independently by every caller.

4. The lookup key — an open decision

The POC looks up by email.

Production candidate: store member_ref as a Galaxy ID attribute — the way employee_ref already works — and look up by that reference. Email then never leaves Galaxy ID.

Tracked as T-LOYALTY-KEY.

5. Effect on entitlement

Member tier is an input to the DMN decision table. See DMN-DECISION-SPEC.md.

⚠️ Every value above is a POC placeholder. The tier names and what each one earns are not confirmed business. See ADR-011 and open question T1 — whether the lever is duration or speed is still undecided.

All of it is editable in the DMN table without touching code.

The entitlement's sourceType records where it came from:

One look at an entitlement record tells you why that person has that access.

6. Degraded behaviour

loyalty.js never throws. Every failure path returns "no tier" with a source field recording why — so the lower tier can be explained afterwards.

The first three are normal. Every other value is logged at warn — otherwise nobody could explain why a GOLD customer received BASIC.

7. Mock data

All synthetic. .test is reserved by RFC 6761 and can never resolve.

Deliberately not a mirror of the Galaxy ID user list. Some members have no Galaxy ID; some Galaxy ID holders are not members. That mismatch is the normal state of two systems owned by different teams, and the platform has to survive it.

The last three are the interesting ones. High tier, no benefit — each for a different reason.

A Galaxy ID user absent from loyalty gets found: false and the baseline. That is the most common case in practice.

8. Fault injection

# Loyalty down — the customer must still get online
curl -X POST localhost:3006/admin/fault -H 'Content-Type: application/json' \
  -d '{"mode":"unavailable"}'

# Loyalty hanging — the login must not hang with it
curl -X POST localhost:3006/admin/fault -H 'Content-Type: application/json' \
  -d '{"mode":"timeout","delayMs":5000}'

# Back to normal
curl -X POST localhost:3006/admin/fault -H 'Content-Type: application/json' \
  -d '{"mode":"none"}'

POST /admin/fault is a test harness with no authentication. Delete it before any deployment.

Measured: with loyalty hanging for 5 s, the login still completes in ~2.1 s and returns the baseline.

9. Open questions

API-OVERVIEW.md · KEYCLOAK-INTEGRATION-SPEC.md · DMN-DECISION-SPEC.md · DATA-CLASSIFICATION.md