TallyPass

TallyPass is a multi-tenant digital pass system for Hong Kong service businesses. Merchants issue package, membership, or attendance passes; customers present a Web Pass or Google Wallet card; staff scan the QR code; and an auditable backend ledger remains the source of truth.

The commercial wedge is prepaid packages for beauty, wellness, fitness, and other session-based services. The underlying engine supports three operating modes:

• Count down — prepaid sessions, such as 10 → 0.
• Count up — loyalty points or stamps, such as 0 → a reward target.
• Log only — attendance or check-ins without a balance change.

Current capabilities

Capability	Status
Merchant dashboard, customers, passes, ledger history, renewal queue, and reports/CSV	Implemented
Confirm-first and auto/kiosk scanning, quantity redemption, cooldown, and manual code entry	Implemented
English and Traditional Chinese merchant, scanner, and customer surfaces	Implemented
Customer Web Pass with configurable fields in fixed positions	Implemented
Google Wallet with a durable pass-state outbox and constrained field layouts	Implemented when Wallet credentials are configured; class/design refresh is best effort
Owner/manager/staff roles, tenant RLS, staff kill switch, and database-enforced TOTP MFA	Implemented
Agency platform administration and feature-gated public signup	Implemented
Apple Wallet, automated outbound reminders, branch UI, and payments	Planned

Wallet cards are display and distribution channels, not the balance authority. Staff-facing reads and every mutation use live backend state because a pass can be screenshotted or temporarily stale.

Stack

• Next.js 16.2 App Router, React 19.2, TypeScript, and Tailwind CSS 4.
• Supabase Postgres, Auth, Row-Level Security, and Storage.
• Direct Google Wallet Loyalty API integration.
• html5-qrcode for camera scanning and qrcode for pass QR rendering.
• Vercel configuration for the Singapore region and the scheduled Wallet worker.

See the architecture guide for the route, data, authentication, and Wallet flows.

Local development

Use Node.js 22 to match CI; the installed Next.js version requires Node.js 20.9 or newer. You also need npm and a Supabase project.

npm ci
cp .env.example .env.local

Fill the required Supabase variables in .env.local and set:

NEXT_PUBLIC_APP_URL=http://localhost:3210

Apply migrations 0001 through 0035 using the database bootstrap guide, then run:

npm run check-db
npm run dev -- -p 3210

Open http://localhost:3210. A bare npm run dev uses Next.js's default port 3000; if you choose that port, update NEXT_PUBLIC_APP_URL to match and remember that the demo seeder still prints port-3210 URLs. Google Wallet is optional for local development.

Verification

Run the same release checks used by CI:

npx tsc --noEmit
npm test
npm run lint
npm run build

The build uses placeholder public environment variables in CI and does not require production secrets.

Useful scripts

Command	Purpose
npm run dev -- -p 3210	Start the local development server on the repository's documented port.
npm run build / npm start	Build and serve the production Next.js application.
npm test / npm run test:watch	Run the Vitest suite once or in watch mode.
npm run lint	Run ESLint across the project.
npm run check-db	Verify connectivity, required tables/RPCs, and schema version 35 or newer.
npm run seed	Destructively recreate the scripted demo business in the Supabase project selected by .env.local.
npm run seed:showcase	Replace the seeded demo's showcase data; run npm run seed first.
npm run provision -- --name ...	Provision a real business and owner non-destructively.
npm run add-admin -- <email>	Create or promote a platform administrator.
npm run mfa:on / npm run mfa:off	Change the database-owned MFA requirement; mfa:off is development-guarded.

All operator scripts target the Supabase project named in .env.local. Check that file before running a destructive or privileged command.

Roles

• Staff use /scan after authentication and MFA.
• Managers can use the scanner and the merchant dashboard, including customers, templates, passes, history, reports, account settings, and security settings.
• Owners also manage business branding and the team.
• Platform admins operate /admin across businesses and can explicitly act as a business.

Documentation

• Product context — users, product purpose, visual principles, and accessibility targets.
• Business strategy — positioning, pricing hypotheses, go-to-market, risks, and roadmap.
• Architecture — current routes, layers, schema, transactions, security, and Wallet synchronization.
• Usage guide — day-to-day merchant, staff, customer, and demo workflows.
• Database bootstrap — create a Supabase project, apply migrations, bootstrap data, and verify it.
• Deployment — Vercel configuration, environment variables, migration rollout, cron, and launch checks.
• Platform admin guide — credential-safe agency operations and recovery procedures.

Files under docs/superpowers/ and docs/dashboard-build-plan.md are dated design/build records, not the current operational source of truth.

Security notes

• Never commit .env.local, service-role keys, Wallet private keys, passwords, pass bearer tokens, or private security reports.
• SUPABASE_SERVICE_ROLE_KEY bypasses RLS and is server-only.
• The first issue response can contain a reusable bearer-token link whose raw token is returned only once. The system also maintains a durable UUID share link; see the identifier model.
• Production deployments should keep MFA enabled and must provide the authenticated daily Wallet/expiry scheduler described in the deployment guide.