How TapMax works — end to end.

What the product does.

1.1What TapMax is

TapMax is an AI-powered smart wallet: it knows every card you own, and at the moment you pay, its routing engine picks the mathematically best one — automatically.

Every card in a wallet earns differently — rotating category bonuses, brand multipliers, promo caps that fill silently, foreign-transaction fees, and points currencies whose real value ranges wildly. No human does that math at the register. TapMax does it on every transaction, and shows its work: every routing decision ships with a full, auditable breakdown of why the winning card won.

1.2The routing decision

When a payment happens, TapMax reads the transaction context and scores every card in the wallet:

• Inputs — merchant, merchant category code (MCC), spend category, brand (if the merchant belongs to a co-brand ecosystem like Delta or Marriott), currency, FX rate and amount.
• Per card — the best matching earn rule, live point valuations, any active promo (with remaining cap), foreign-transaction fees, and progress value toward the user's active goal.
• Output — a ranked list, a winner, the margin over the runner-up, and a plain-language explanation ("Why this card?") derived from the same numbers.

Multipliers alone are misleading — 6× of a point worth 0.85¢ can lose to 2% flat cash back. TapMax converts everything to a single currency-equivalent value per transaction, so a "3× dining" card and a "6× brand" card compete on actual value, not marketing.

1.3Goal modes

The best card isn't always the one that earns the most cash-equivalent today. TapMax lets the user declare what they're optimizing for, and the engine re-weights accordingly:

The signature demo moment: at the hero dinner scenario, the brand-match hotel card narrowly beats the 3×-dining card on pure value — but switch the goal to Race to Status and the airline card flips to the top, because status miles are suddenly worth chasing. Same engine, same math, different objective.

1.4Screens & flows

1.5Onboarding

A first-time visitor lands on onboarding before anything else. Four steps:

1. Sign up — mock social logins (Apple + Google everywhere; UAE adds UAE PASS, Singapore adds Singpass) with a prefilled email and a regionally formatted phone number.
2. Link your cards — connect the cards you already own.
3. Scan to add — a camera-viewfinder mock detects a physical card and adds it.
4. Tap anywhere — you're routed to the wallet, ready to pay.

Onboarding can be replayed any time from Settings.

1.6Demo scenarios

Every market ships the same five scenario archetypes, each engineered to showcase one dimension of the engine:

1.7The four markets

Each market is fully localized: local currency and number formatting, local earn conventions (points per $1 vs. per ₹100 / AED 100 / S$100), local card ecosystems, and local sign-in options.

1.8Presenter tools

• Press D inside any demo for the presenter drawer — jump straight to any scenario with its talking-point hook.
• Press P for present mode.
• Settings → reset demo restores the seeded state (promo caps, goal progress) at any time.

1.9The Rewards Leak Audit

The public top-of-funnel at gettapmax.com/audit: a 60-second, no-login tool that estimates how much value a visitor's current wallet leaks every year. Pick a market, pick your cards, describe how you pay today, set monthly spend — the audit compares your behaviour against your own wallet's ceiling (and the market's best cards) using public reward rates for 1,000+ tracked cards, entirely in the browser.

• Three result modes — a leak (default), a discipline dividend for self-declared optimizers, or a ceiling comparison against the market's best cards.
• Email-gated report joins the waitlist automatically; sharing generates a referral code that moves the sender up the list.
• The methodology line states every assumption on the result screen.

How TapMax makes money.

2.1The value we capture

TapMax monetizes a delta that already exists: the gap between the rewards consumers are entitled to and the rewards they actually collect.

Every suboptimal swipe leaves value on the table — the wrong card at dinner, a promo cap nobody tracked, a 3% FX fee that silently erased the points. TapMax recovers that value for the user on every transaction, and takes its economics from the surplus it creates and the transaction flow it now sits inside. The user never pays for routing out of pocket; the model is aligned — TapMax earns when the user earns more.

2.2Revenue streams

The planned model stacks four streams, sequenced from launch onward:

Longer term, the routing engine itself is licensable: banks and issuers in rewards-dense markets can embed "best card" intelligence in their own apps as a B2B API.

2.3Why now

2.4Market strategy

The four launch markets — US, India, UAE, Singapore — were chosen because each is rewards-dense with multi-card consumers, yet each breaks a naive one-market product in a different way:

• US — the deepest co-brand ecosystem and the archetypal status race (airline elite tiers driven by qualification dollars).
• India — explosive premium-card growth, distinct earn conventions (points per ₹100), lakh/crore formatting, and ecosystem cards (Amazon Pay, Air India).
• UAE — an expat, travel-heavy population where FX fees and Skywards tier miles dominate the math.
• Singapore — the most sophisticated miles-chasing culture in Asia; KrisFlyer elite currency and bank-specific dining ecosystems.

Building all four in parallel forced the engine to be genuinely market-independent from day one: same scorer, different data. Entering market five is a data exercise, not an engineering one.

2.5Current status

• A real native iOS app is live on TestFlight — real accounts, a grounded multi-market card catalog, on-device routing, and the Burn redemption optimizer (see Part 4).
• Four fully interactive market prototypes live at gettapmax.com, running the same deterministic routing engine on simulated data.
• Growth funnel live: the Rewards Leak Audit feeds a referral waitlist.
• The demos process no payments and collect no user data; demo state lives entirely in the visitor's browser.
• Waitlist open on the landing page — investors can flag themselves for the deck.

Under the hood.

3.1Architecture

Four market-localized client-side React apps plus a static marketing site, all served from one domain. No backend: the engine runs entirely in the browser and state persists in localStorage.

The four market apps share an identical architecture; only src/data/ (cards, merchants, valuations, goals) and localized formatting differ. The engine code is market-agnostic by construction.

Runtime architecture. Screens hand a transaction to the engine, which scores it against the market's card data; nothing leaves the browser except the optional, user-keyed Claude call.

3.2The routing engine

src/engine/route.ts is a pure, deterministic scorer — no randomness, no network, no hidden state. Same inputs, same ranking, every time.

Earn-rule matching. Each card carries a list of earn rules. When several rules could match a transaction, a strict internal precedence picks exactly one — rules never stack.

A Marriott dinner is simultaneously a brand match (marriott), an MCC match (5812) and a category match (dining) — precedence selects one. Every card has a base rule, so a match always exists.

Promo bonuses are cap-aware with partial fill. A quarterly "5% at grocery stores" promo has a spend cap. The engine tracks consumption; when a transaction would overflow the remaining cap, the bonus applies only to the portion that fits:

The engine tracks consumption and applies the bonus only to the spend that still fits under the cap — never all-or-nothing.

FX fees are subtracted, not footnoted. Foreign-currency transactions charge the card’s FX fee against the score — which is how a 2%-flat card with a 3% FX fee goes net-negative in London and falls to the bottom of the ranking.

Goal value has two components:

• Status currency — status units earned are valued at a per-mode weight; Race to Status boosts that weight substantially, which is what produces the goal flip.
• Milestone credit — under Hit Spend Milestone, spend toward the target earns a pro-rata share of the bonus, capped at the remaining need.

The final ranking sorts by total score; ties break deterministically by card order. The result object carries the winner, runner-up, margin and the full per-card breakdown that powers every explanation in the UI.

3.3Money units per market

All amounts are integers in local minor units; earn multipliers follow local conventions:

3.4Engine modules

3.5Data model

Per-market demo data lives in src/data/:

• cards.ts — the wallet. Each Card declares its points currency, FX fee rate, earn rules (with match kind + multiplier), cap-limited promos, optional status-earn rate, and card-face art. Also exports default point valuations (editable in Settings), the default goal config, and seeded promo-cap consumption.
• merchants.ts — the scenarios. Each Scenario is a full transaction (merchant, MCC, category, optional brand, currency, FX rate, amount) plus a presenter hook and a flow tag (tap or checkout).

3.6Client state

Everything persists in the browser — there is no server-side state anywhere:

3.7Testing

Each market repo carries 57 Vitest tests that pin the routing and Burn engines to exact outputs — not just "card A beats card B" but the precise value to the cent. The five scenario archetypes are encoded as invariants in every market:

• The hero-dinner close call (e.g. US: Bonvoy $6.12 vs. $5.76; SG: Platinum S$61.20 vs. DBS S$57.60).
• The goal flip under Race to Status (US: flips to Delta at $6.96; SG: to KrisFlyer at S$77.40).
• The grocery promo cap partial fill.
• The London FX scenario where fee-bearing cards go net-negative.
• The spend-milestone goal routing to the promo card.

Because the scorer is pure, the tests are the spec: any data or engine change that shifts a demo moment fails the build before it can break a live pitch.

3.8Repos & deployment

Build & deploy pipeline. Each app repo builds with its per-market base path; the bundles land in the site repo, and a push rebuilds gettapmax.com in about thirty seconds.

Each app builds with a per-market base path (vite build --base=/us/ etc.); the bundles are copied into the site repository, which GitHub Pages serves over the custom domain with enforced HTTPS. The landing page and this documentation are deliberately hand-crafted static HTML — zero dependencies, zero build step, nothing to break.

Beyond the demos: the shipping product.

4.1The iOS app — live on TestFlight

TapMax is no longer only a prototype. A native iOS app (SwiftUI, iOS 16+) is live on TestFlight with real accounts, a real card catalog, and the same deterministic routing engine running on-device — join the beta.

• Real accounts — email one-time code, Sign in with Apple, or Google. Each user's wallet lives in their own database row.
• Catalog-first wallet — add cards by searching the grounded catalog and multi-selecting; no card number required. Scanning is optional: camera, NFC tap, or typed entry, all validated on-device with only the last 4 digits ever kept.
• Multi-market — pick your country at sign-up (UAE, India, Singapore, US) and the catalog, currency and conventions follow; changeable in Settings.
• On-device routing — the engine scores the wallet locally; goals are wallet-derived (a status race is only offered when you own a status-earning card).
• Location nudges — with permission, arriving at a hotel, restaurant or store triggers a notification naming the best card for that merchant. Location is processed on-device and never uploaded.
• Pay-moment widget — a Lock Screen and Home Screen widget keeps the wallet's current best card visible right where you look before you pay (rolling out in the next TestFlight build).
• TapMax Pro — the free tier routes a capped wallet; Pro unlocks unlimited cards, via subscription or by referral rewards.

4.2The card catalog & data pipeline

Routing is only as good as the card data underneath it. TapMax's catalog is grounded, not guessed: earn rates, fees, exclusions and benefits are extracted from official issuer pages and terms documents across all four markets — a tracked universe of 1,000+ cards and issuer source pages.

• Deterministic validation gate — every catalog entry must pass a strict automated validator (rate plausibility, structure, market conventions) before it can be published. Nothing invalid can reach the app.
• Daily watcher pipeline — issuer pages are monitored for changes. Low-risk updates (benefits, promos) publish automatically at high confidence; anything touching fees or new cards is held for human review.
• Honest labeling — where a point's cash value isn't published by the issuer, the catalog stores it as a stated assumption, never as fact.
• The same catalog powers the app, the routing engine, and the public leak audit — one source of truth.

4.3Burn — the redemption optimizer

Earning points optimally is half the problem; most value dies at redemption. Burn ranks what your existing balances are actually worth: every direct redemption and transfer-partner route, ordered by real value per point.

• Deterministic and balance-independent — rankings come from redemption rates alone, so they never shuffle as your balance changes; balances only determine what you can afford today.
• Value traps flagged by math — a 3:1 hotel transfer that looks generous ranks exactly where its value puts it: last.
• No LLM anywhere in the ranking path, no auto-published rate changes — every catalog update is human-approved, and devaluations generate alerts.
• Live in the app and in all four demos; balances are always user-entered — TapMax never asks for loyalty-account credentials.

4.4Privacy & security posture

• No full card numbers, ever — scans and typed numbers are validated on-device and immediately reduced to the last 4 digits plus the issuing bank; the full number is never stored or transmitted.
• Per-user data isolation — wallet rows are protected by row-level security; a user can only ever read their own data.
• On-device intelligence — routing decisions and location processing happen on the phone.
• The demos collect nothing — no accounts, no analytics beyond the page itself, state in the visitor's own browser.
• Account deletion is built in and recomputes entitlements; subscriptions are managed through the App Store.