Developer guide

Stack

Next.js (App Router, server actions), TypeScript (strict), Prisma with PostgreSQL 16, Tailwind CSS, Zod and Vitest.

Local setup

cp .env.example .env         # fill AUTH_SECRET, ENCRYPTION_KEY, DATABASE_URL
npm install
npm run db:deploy && npm run db:seed    # SEED_DEMO=1 for demo data
npm run dev                  # http://localhost:3000
npm run worker               # jobs: email, automations, billing lifecycle

Or run everything with docker compose up.

Tests

npm run typecheck && npm run lint
npm test                     # unit + integration (needs TEST_DATABASE_URL)
npm run test:e2e             # Playwright browser flows (needs a running app)

Architecture

• server/ holds the domain services. Each checks tenancy (requireWorkspace, scoped) and permissions.
• app/actions/ holds thin server actions that call services.
• app/api/v1/ holds the REST API via apiHandler (rate limits, auth, CSRF, errors).
• server/payments/ has one adapter per provider behind a single interface.
• server/jobs/ is a Postgres job queue, drained by workers/scheduler.ts.

See docs/ARCHITECTURE.md, docs/SECURITY.md and docs/DEPLOYMENT.md in the repository.

Adding a payment provider

Implement PaymentProvider (server/payments/types.ts): createCheckout, parseWebhook (verify the signature and return normalised events) and refund. Then register it in server/payments/registry.ts. Fulfilment, idempotency and amount checks are shared.