# Loyalty Frontend Architecture

**Status:** Production scaffold — connected to Loyalty service 7.0–7.6  
**Package:** `frontend/modules/loyalty/`  
**Routes:** `frontend/app/loyalty/` (thin App Router only)  
**BFF:** `frontend/app/api/loyalty/[...path]` → `:8004`

## Layers

1. **App Router** — `page.tsx` / `layout.tsx` / `loading.tsx` / `error.tsx` / `not-found.tsx` only
2. **Module package** — features, components, services, design-system, constants
3. **Shared DS** — `@/components/ds` + module tokens `--loyalty-*`
4. **BFF** — same-origin proxy with `Authorization` + `X-Tenant-ID`

## Portal

Single portal `engage` under `/loyalty/engage/*` with shell navigation. Hub at `/loyalty/hub`.

## API client

`loyaltyApi` in `modules/loyalty/services/loyalty-api.ts` covers programs, tiers, members (+lifecycle), point accounts (+ledger ops), rewards/redemptions, campaigns (+lifecycle), referrals, wallets, audit, health.

## Query keys

`["loyalty", tenantId, resource, ...]`

## Out-of-scope honesty

Screens without backend APIs (gift cards 7.7, gamification entities, segments, partners, branches, API keys) use `LoyaltyScopeNotice` — no fake CRUD.