LCLoyalty Cash
Technical architecture

How Loyalty Cash is built

Next.js App Router on Vercel, multi-tenant program hosts on loyalty.cash, Auth0 user pool, Supabase Postgres, and an mCards adapter layer that switches between mock and live staging credentials.

Multi-tenant programs

  • · Apex: loyalty.cash — platform marketing, merchants, co-brand intake
  • · Programs: {org}.loyalty.cash → middleware rewrites to /cobrand/{org}
  • · Examples: nfl.loyalty.cash · nba.loyalty.cash · f1.loyalty.cash
  • · Path demos: /cobrand/nfl still works on any host before DNS is live

Runtime stack

  • · Frontend: Next.js 14, React 18, Tailwind CSS v4, Framer Motion
  • · Hosting: Vercel · production branch · loyalty.cash (programs: org.loyalty.cash)
  • · Auth: Auth0 (`mrewards-users`) — wired when login is required
  • · Data: Supabase Postgres via `DATABASE_URL` (ready; prototype state is client-side for demo speed)
  • · Graph: In-memory domain model + canvas force simulation (Obsidian-style)
  • · mCards: HMAC client + mock/live adapters (`lib/mcards`) — Cards & Currency APIs per mcards.readme.io

What is live / mocked / production-ready

LiveDeployed app, health checks, custom domain, Vercel env (Auth0, Supabase, DATABASE_URL)
SimulatedAlex Morgan profile, Home Depot journey economics, Scanit receipt OCR, exchange rates, Value Concierge (deterministic graph-aware responses)
Adapter-readyCards API, Currency API, webhook-shaped transaction events — swap mock → live via `MCARDS_API_MODE=live` + staging keys
Production pathPersist graph nodes/edges in Postgres, Auth0 session gating, real Scanit webhook, partner conversion contracts

Domain model

Graph nodes: consumer, card, transaction, merchant, brand, product, receipt, reward, currency, offer, goal, interest, payment_account, insight, partner, campaign.

Relationships: owns, used, transacted_at, contains, purchased, earned, eligible_for, funded_by, converts_to, interested_in, recommended_by, and more.

Key routes

  • / — Landing
  • /app — Today dashboard
  • /app/graph — Rewards Graph
  • /app/wallet — Value Wallet
  • /app/exchange — Currency exchange
  • /app/receipt — Scanit simulator
  • /app/offers — Ranked offers
  • /app/concierge — Value Concierge
  • /app/demo — Guided journey
  • /app/score — Value Score
  • /architecture — This page
  • /partners — Partner economics
  • /demo-story — 10-min script
  • /health — Uptime