Appearance
App flows
Twelve screen flows of the mobile app, mapped stage by stage onto the mobile API endpoints. They are working specs, not a description of finished behaviour: the open questions at the foot of each page are the decisions still to make.
The flows
Five areas have their own sections in the sidebar, under Mobile API, because they are documented further than the rest:
- User Authentication — sign up, login and forgot password, each playable step by step against a phone, plus How authentication works for the mechanism underneath them (tokens, OTP lifecycle, account states, failure semantics).
- E-commerce — Shop to order, the whole buying journey in one playable flow, with the listing, product/cart and payment pages going deeper on one leg each.
- Product Authentication — Scan to claim: verifying a code on a label and claiming the points and collectible behind it.
- Rewards — Earn and spend: campaign progress and claiming, then spending the reward in the cart.
- Collectibles & Trading — Collect and trade: the vault, the open-trade board and the trading hub, with the four trade types and the four ways a reply can end.
| Flow | Section | Starts at | Ends at |
|---|---|---|---|
| Sign up | User Authentication | Sign up link | Home page, via OTP |
| Login | User Authentication | Login page | Home page, via Google, guest skip, or email + password |
| Forgot password | User Authentication | Forgot password link | New password set |
| Shop to order | E-commerce | Shop listing | Order placed |
| Shop listing | E-commerce | Shop listing page | All-items and filtered states |
| Purchase | E-commerce | Product display page | Shipping page, "Go to payment" |
| Payment | E-commerce | Payment page | Order placed (undefined) |
| Scan to claim | Product Authentication | Scanner | Points and collectible claimed |
| Earn and spend | Rewards | Rewards screen | Reward claimed, then applied to a cart |
| Collect and trade | Collectibles & Trading | Vault or open-trade board | Card claimed, traded, or an offer left waiting |
| Threads | More app flows | Threads tab | Post liked, commented on, or written |
| Template pages | More app flows | Home page | Profile, referrals, store locator, contact, order history, cancel and pay again |
Threads — the community feed: posts, likes, comments and the compose screen — is the odd one out. Its screens ship, and almost every call behind them is undocumented, because a separate feed service serves it. That page says exactly what is missing rather than guessing at it.
How to read the mapping tables
Eight pages open with a player — the three authentication flows, Shop to order, Scan to claim, Earn and spend, Collect and trade and Threads. Press Play and the steps advance while the phone beside them shows the screen each one is on, with the field or button that step touches ringed. The rest are static: a diagram plus the table below it.
Each stage in a diagram carries a number, and the API calls by stage table on the page is keyed by it. Three kinds of row appear:
- A documented endpoint, linked to its entry in the endpoint reference. Take the field lists there as the contract.
- An inference, marked as unverified in the text. These are places where a screen clearly needs data that the API probably returns, but the response shape isn't documented — confirm against the backend before building.
- A gap: no endpoint exists. The payment page has two of these, and they are the most important thing on that page. Threads is almost nothing but gaps, and the player labels each step that is one.
Every call needs the brand x-auth-token; rows marked Customer need the customer JWT as well. See the overview for both headers, and quirks before wiring up error handling — a failed request usually still answers 200 OK.
What is not covered
No flow exists yet for the parts of the app the API clearly supports: mini-games, receipts and events. The endpoint pages document those; the screens have not been specced.
The reverse case is Threads: the screens exist and ship, and the API behind them does not appear in either backend.