Getting Started Overview

The repository currently has three runtime surfaces:

• Web app: Next.js App Router application
• Core backend: Convex functions, schema, and HTTP routes
• Support backend: FastAPI service for wallet passes, add-ons, some payment flows, and gateway proxied APIs

Minimum baseline

Use these versions as the safe baseline for the full repo:

• Node.js 20+
• pnpm 9+
• Python 3.11+ for the optional FastAPI backend

Node 20 is the right default because the Docusaurus docs app depends on it, and it is also the safest baseline for the current web tooling.

Core commands

From the repo root:

pnpm install
pnpm dev
pnpm build
pnpm lint
pnpm typecheck

Convex runs separately:

npx convex dev

The current root pnpm dev script starts the Next.js app only. It does not start Convex automatically.

Docs site commands

The Docusaurus site is isolated in docs-site/:

pnpm docs:install
pnpm docs:dev
pnpm docs:build
pnpm docs:serve

Repo landmarks

• app/: pages, layouts, API routes, and route groups
• components/: feature components and UI primitives
• convex/: schema, queries, mutations, actions, and HTTP routes
• lib/: shared utilities such as money formatting, sitemaps, and deployment ingest helpers
• backend/: FastAPI service and provider integrations
• mobile/: mobile gateway docs and typed API client
• tests/: Python integration and API tests

Suggested onboarding path

1. Configure environment variables from Environment Variables.
2. Start Convex with npx convex dev.
3. Start Next.js with pnpm dev.
4. Start the Python backend only if you need mobile gateway proxy flows, wallet passes, badge generation, or backend-only payment endpoints.