Training Sanctum

A personal flashcard / spaced-repetition study app. Color and editorial grid rhythm borrowed from spy-family.net; app structure and component shapes from Quizlet's library and flashcard-study surfaces, without Quizlet's gamification or social layer. Dual-theme (dark default, sage/white light theme), single-user in v1.

See _bmad-output/planning-artifacts/ for the product brief, PRD, UX designs, and architecture spine this app is built from.

Stack

• Next.js 16 (App Router, Turbopack, TypeScript)
• Prisma 7 + Postgres (Neon), accessed only through packages/db
• Tailwind CSS v4 (tokens mapped from DESIGN.md)
• Zod for request/env validation
• Vitest (domain unit tests) + Playwright (API and E2E suites)
• npm workspaces monorepo — no Turborepo, no pnpm

Repository layout

apps/
  web/                 # the Next.js deployable
    app/               # routes, API route handlers, components
    lib/               # env validation, API fetch wrappers
packages/
  domain/              # pure TypeScript domain logic — zero framework/DB imports
  db/                  # Prisma schema, generated client, migrations
tests/
  domain/              # Vitest — packages/domain
  api/                 # Playwright request-fixture suite
  e2e/                 # Playwright browser suite

packages/domain has zero imports from next, react, or @prisma/client (enforced by packages/domain/eslint.config.mjs); the only client-server boundary is apps/web/app/api/**/route.ts; Postgres is reachable only through the Prisma client exported by packages/db. See _bmad-output/planning-artifacts/architecture/architecture-Web_TrainingSanctum-2026-11-01/ARCHITECTURE-SPINE.md for the full set of architectural decisions these rules come from.

Getting started

1. Copy .env.example to .env.local and fill in DATABASE_URL (a Neon Postgres connection string) and BETTER_AUTH_SECRET. The app validates these at process start and fails fast with a clear error if either is missing or malformed.

2. Install dependencies and generate the Prisma client:

   npm install
   npm run db:generate
   

3. Apply the schema to your database (first run / after a schema change):

   npm run db:migrate:dev
   

4. Start the dev server:

   npm run dev
   

   The app runs at http://localhost:3000.

Common commands

Command	What it does
npm run dev	Start the Next.js dev server (Turbopack)
npm run build	Production build of apps/web
npm run typecheck	TypeScript check across all workspaces
npm run lint	ESLint across all workspaces
npm test	Vitest — packages/domain unit tests
npm run test:api	Playwright — API/integration suite
npm run test:e2e	Playwright — browser E2E suite
npm run db:generate	Regenerate the Prisma client
npm run db:migrate:dev	Apply/create migrations locally (prisma migrate dev)
npm run db:migrate:deploy	Apply committed migrations (CI/production)

Deployment

See DEPLOYMENT.md for the manual steps to link a Vercel project and a Neon database (production + PR preview branches) and get a live URL.