TapAccess Web

Next.js 16 (App Router) + React 19 + Tailwind CSS 4. The admin dashboard and the public NFC profile pages for TapAccess. All data comes from the TapAccess API.

Setup

npm install
cp .env.example .env.local
npm run dev          # http://localhost:3001  (the API must be running on :4000)

Variable	Exposed to browser	Purpose
API_URL	no	Where the Next.js server and the /api + /uploads rewrites reach the API
INTERNAL_API_KEY	no	Required in production. Must match the API's INTERNAL_API_KEY; lets the API trust the visitor IP forwarded by the Save contact / tracking route handlers
SESSION_COOKIE_NAME	no	Must match the API's COOKIE_NAME (default tapaccess_session)
NEXT_PUBLIC_SITE_URL	yes	Public base URL. Card URLs are <SITE_URL>/c/<slug>, so set your final domain before writing any NFC tags

No secret is ever prefixed NEXT_PUBLIC_. The admin session cookie is HttpOnly and set by the API through the same-origin /api rewrite, so JavaScript never sees it.

Routes

Route	Rendering
/	static	Neutral landing page (does not link to the dashboard)
/c/[slug]	dynamic SSR, no-store	Public profile; loading, error, not-found and unavailable states; Open Graph + theme-colour metadata
/login	client	Admin sign-in; ?next= is restricted to /admin… paths
/admin	client	Overview: stat tiles, visits over time, top and recent cards
/admin/cards	client	Search, filter by status/package, sort, paginate, row actions
/admin/cards/new	client	Create a card (live slug availability, package picker)
/admin/cards/[id]	client	NFC setup (URL, QR, NFC Tools steps), details, analytics
/admin/cards/[id]/edit	client	Visual editor with live phone preview
/admin/settings	client	Display name, change password

proxy.ts redirects signed-out visitors from /admin/* to /login. This is only a UX shortcut: the API verifies the session on every request.

Layout

app/                     routes (see above)
components/
  profile/               public card renderer, shared by /c/[slug] and the editor preview
    profile-view.tsx       hero, quick actions, Save contact / Share
    profile-sections.tsx   about, buttons, contact, hours, services, products, promotions, gallery…
    theme.ts               theme → CSS variables and button styles
    tracking.tsx           visit/click beacons (no cookies, no storage)
  admin/                 dashboard shell, charts, card actions, packages, editor/
  ui/                    button, fields, dialog, confirm, menu, badges, feedback
lib/
  api.ts                 browser API client (same-origin /api)
  server-api.ts          server-only public profile fetch
  plans.ts               package rules (mirror of the API's)
  constants.ts, types.ts, fonts.ts, utils.ts

Profile pages use container queries rather than viewport breakpoints, so the editor's 375px phone frame renders exactly like a real phone.

Images are uploaded already resized WebP, so profiles use plain <img> with lazy loading instead of next/image. That avoids per-storage-host image configuration and the Vercel image-optimization quota.