Pointili
Mobile-first PWA loyalty cards for local businesses.
Customer: Scan → Stamp → Done. Merchant: Open QR → leave it running.
Next.js 16 (App Router) · TypeScript · Tailwind CSS v4 · Supabase (Postgres, Auth, Storage).
Run
npm install
cp .env.example .env.local # fill in; never commit .env.local
npm run migrate # applies supabase/migrations (idempotent), promotes admins, sets auth config
npm run dev # http://localhost:3100
| Script | What it does |
|---|
npm run migrate | Replays every migration over the Supabase Management API (HTTPS), promotes ADMIN_PHONES / ADMIN_EMAILS, closes public sign-up |
npm run test:e2e | Spec §50 acceptance scenario + replay, race, claim and authorization checks against the real database (throwaway users, cleaned up) |
node scripts/demo.mjs | Ensures the demo merchant Café Bonheur (phone 20 000 001, password in .env.local → DEMO_MERCHANT_PASSWORD) and prints a fresh scan URL |
node scripts/reward-flow.mjs | Real two-browser test of the reward QR: 10 stamps → "Use reward" → staff scans the QR on /redeem → confirm → both screens update; a used QR is refused |
node scripts/shots.mjs | Phone-size screenshots of every screen with a sideways-overflow check (needs npm run dev and Chrome) |
npm run sql -- "select 1" | Run SQL over HTTPS |
npm run icons | Regenerate PWA icons |
Routes
- Public:
/, /how-it-works, /pricing
- Customer:
/customer/register, /customer/login, /customer/forgot-password, /customer (home), /customer/cards/:id, /customer/rewards, /customer/rewards/use/:id, /customer/profile, /customer/scan
- Scan link (what the QR encodes):
/scan/:token
- Counter QR link (printed, never changes):
/join/:code
- Merchant:
/login, /welcome (first sign-in) → /loyalty?welcome=1 → /welcome/ready, /dashboard, /qr, /counter-qr, /loyalty, /customers, /customers/:id, /redeem, /activity, /analytics, /billing, /settings
- Admin:
/admin, /admin/businesses, /admin/subscriptions, /admin/payments, /admin/customers, /admin/activity, /admin/traffic (+ /admin/traffic/visit/[session], /admin/traffic/clicks), /admin/system
How it works
Accounts. Everyone signs in with a Tunisian phone number + password (merchants and admins may also use their email). Supabase Auth stores the password; the auth identity of a phone account is a synthetic address [email protected], because Supabase's phone provider would need an SMS provider just to create accounts. Public sign-up through the Auth API is disabled — accounts are created only by the server (validated number, rate-limited). Owners never sign up: Pointili opens every shop from the admin console (/admin/businesses/new → admin_create_business) and sets its plan (admin_grant_plan); there is no /register, and the database has no function an owner could call to open a shop or buy a plan himself. Customers still register themselves at /customer/register.
The QR. /qr mints a single-use token (mint_qr_token: 24 random bytes, only the SHA-256 is stored, 60 s life). The screen polls every 2 s and rotates as soon as the token is used or 15 s before it expires; each stamp flashes "+1 STAMP · #code". A Wake Lock keeps the screen on.
The stamp (collect_stamp, one transaction, row locks on token and card): token exists → not used/expired → business active and subscribed → not the merchant's own business → card active → per-customer cooldown (default 1 h) → insert stamp, mark token used, bump balance → return progress and newly unlocked rewards. Two phones scanning one QR, or one phone double-submitting, yields exactly one stamp.
The counter QR (printed). /counter-qr shows a poster with a permanent QR to /join/<businesses.join_code> — print it (A4) or download the PNG. It only adds the card to the customer's phone with 0 stamps (join_card; scanning again just opens the card), so a photo of it can't earn anything. Signed out, the join page shows the card (join_card_preview, service role) and sends the person to register / log in, then back to add the card. Stamps still come only from the live /qr.
Signed-out scans. The scan page POSTs (never a GET side-effect, so link previews can't burn tokens). Signed out, the server reserves the token for that browser with an httpOnly claim cookie for 20 minutes, so a first-time customer can register and still get the stamp; the merchant screen rotates immediately.
Rewards. Unlocked when balance ≥ reward stamps. The customer taps "Use reward" → a 6-digit code (15 min) → the merchant confirms at the counter (/redeem, live list) or from the customer page. Stamps are deducted only on merchant confirmation, under a lock, so a reward can't be redeemed twice or remotely.
Levels. A card can carry gifts on the way to its goal — say 6 → a cappuccino, 10 → a croissant, 20 → breakfast — set on the card itself (save_loyalty_card(p_levels), up to four, each below the goal). Taking a level costs no stamps and is allowed once per card (customers.levels_claimed); the goal spends its stamps and opens the levels again; an expired card starts over with them (0012_card_levels.sql). Every screen marks the levels on the stamp grid, and a taken one reads "taken".
Changing the card later is fair. Each customer's card remembers the goal it started with (customers.card_target). Raising the stamps required never takes a reward away from someone mid-card — they finish at their old goal and the next card uses the new one. Lowering it helps everyone immediately (reward_cost = the lower of the two). Extra stamps past a full card carry over. The loyalty page shows who a change affects (merchant_card_impact) and asks for confirmation before saving.
Card design. Owners design their own card at /loyalty/design: a style (Bold, Classic, Soft, Midnight, Photo, Minimal) built from their main colour, then background colour/gradient/pattern, stamp look (icon, their logo, check, heart, star) and colour, light/dark text, cover photo as background, and a short line under the name — with a live preview. Stored as loyalty_cards.design, validated by clean_card_design() (SQL) and resolveDesign() (lib/card-design.ts), rendered everywhere by components/LoyaltyCardVisual.tsx. New owners land in the designer right after creating their card.
Traffic (first-party analytics). components/analytics/Beacon.tsx, mounted in the root layout, records page views, engaged time (only while the page is on screen and touched in the last 3 minutes) and taps — as a share of the width plus the page y — and sends them in batches to app/api/ev (never through proxy.ts, so a batch sent while a page closes can never be the request that rotates a session). The route verifies the auth cookie to attach the account, adds the country/city Vercel gives it and the device read from the user-agent, and writes public.analytics_events with the service key; sign-ins and customer sign-ups are recorded by app/actions/auth.ts. No third-party script, no IP address, no query string, and dynamic segments (/scan/:token, /join/:code, ids) collapsed; a field tap records its name, never its value. The console is not tracked. /admin/traffic (tabs: summary, visitors with live-now, weekday × hour heatmap of visits and of stamps, sources, pages) and the click map read it only through the admin_traffic* functions (require_admin); by default they leave out robots, localhost/preview traffic and any browser ever signed in as an admin — "with my visits" includes them.
Navigation & forms. Every screen except the three home screens (/customer, /dashboard, /admin) has a back button that returns within the visit or to the parent page (components/nav/BackButton.tsx; sign-in screens and processed scans are skipped). Server-action forms submit through lib/use-form-action.ts, so a failed sign-up or login never clears what was typed.
Branding. Owners upload a logo and a cover photo (loyalty page or settings). The browser crops and compresses them (logo 512², cover 1600×700, WebP/JPEG) before upload; they appear on customers' cards and behind the QR screen.
Billing. The founder sets every plan: at creation (30-day trial, 6 Months 80 TND or Yearly 120 TND, with the password he agrees with the owner), then from the shop page — any plan until any date at any price (admin_set_subscription: the running period ends, the new one starts today, a price above 0 is recorded as a payment) or +30 days (admin_extend_subscription). Payments are a history under Subscriptions. An expired subscription pauses the QR; customers keep their stamps.
The owner's first sign-in. A shop the founder opens starts with onboarded_at null: the owner lands on /welcome (what the founder set is shown, never asked again; he adds his logo, address and Instagram — finish_welcome), then makes his card, then /welcome/ready sends him to the QR.
Security model
- Every value-changing operation is a
security definer function identifying the caller with auth.uid(); ids, roles and business ids from the browser are never trusted.
- RLS is enabled and forced on every table; signed-in users can only
select their own rows (or their business's). No table is writable by anon or authenticated.
- Function
EXECUTE is revoked by default and granted one by one; 0003_security.sql fails the migration if anon can execute anything.
- Service-role key is server-only (
import "server-only"), used for account creation, the anonymous claim, password resets, logo uploads, and admin password resets after an admin check.
- Rate limits live in Postgres (
rate_limits): login per phone and IP, registration, stamps per user, QR minting per business, code lookups, password reset requests and verification attempts.
Deploy (Vercel)
Live: https://pointidi.vercel.app — Vercel project pointidi (team nexesmissions-projects, Hobby), functions in dub1 next to Supabase eu-west-1.
Production env vars on the project: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY (type config, it is public by design), SUPABASE_SERVICE_ROLE_KEY (secret). QR and reward-QR links use the request's own host, so no site URL variable is needed.
Deploy the committed branch from a git-free export — on the Hobby plan Vercel blocks CLI deployments whose git commit author isn't a member of the Vercel account (TEAM_ACCESS_REQUIRED), and an export has no commit metadata:
rm -rf ../pointidi-deploy && mkdir ../pointidi-deploy && git archive pointidi-v1 | tar -x -C ../pointidi-deploy
cd ../pointidi-deploy && npx vercel link --yes --project pointidi --scope nexesmissions-projects && rm -f .env.local
npx vercel deploy --prod --yes --archive=tgz
Then check it: SHOTS_BASE=https://pointidi.vercel.app node scripts/shots.mjs and SHOTS_BASE=https://pointidi.vercel.app node scripts/reward-flow.mjs. (Do not use vercel deploy --temporary: anonymous deployments are capped at 20 functions.)
Needs an external account before launch
- SMS for password reset. Set
SMS_PROVIDER=twilio + TWILIO_*. Without it, codes are shown on screen in development only; in production an admin can issue a temporary password from /admin/customers.
- Hosting. Deploy on Vercel (or any Node host) with the variables from
.env.example, set NEXT_PUBLIC_SITE_URL to the public origin, and re-run npm run migrate so Supabase Auth's site URL matches.
- Payment details. Optionally set
NEXT_PUBLIC_SUPPORT_PHONE / NEXT_PUBLIC_SUPPORT_EMAIL so merchants see who to pay on /billing.
