Getting Started

• Professional developers who want a battle-tested architecture with clean abstractions, 500+ unit tests, and production-hardened patterns.
• AI-assisted builders (using Cursor, Lovable, Windsurf, etc.) who want a working SaaS backend they can scaffold their app into without building billing, auth, and admin from scratch.

The normal repo path is PostgreSQL from day one. If you want the least friction while staying on the same migration lane you'll deploy later, use local PostgreSQL or a hosted PostgreSQL database.

Useful starting points:

• Official PostgreSQL downloads
• Official PostgreSQL Docker image
• Neon docs
• Supabase database docs
• Railway PostgreSQL docs

Typical local PostgreSQL shape:

DATABASE_URL="postgresql://USER:PASSWORD@localhost:5432/DBNAME?schema=public"

cp .env.example .env.local

This creates your local environment file. The template comes pre-configured with sensible defaults — including AUTH_PROVIDER="nextauth" so you can start without any third-party accounts.

npm run prisma:deploy

This reads env values through prisma.config.ts, so the Prisma CLI picks up your local .env.local automatically. It then creates or updates your local database from DATABASE_URL and applies the existing migration history.

In this repo, that existing migration history is PostgreSQL. DATABASE_URLchooses the target database, but it does not switch Prisma's datasource provider, and Prisma 7 does not support provider = env("DATABASE_PROVIDER").

Use npm run prisma:migrate -- --name your-change later only when you intentionally change prisma/schema.prisma and need to generate a new migration. For a fresh install, npm run prisma:deploy is the correct command.

If Prisma reports a failed old migration on a supposedly fresh setup, inspect the resolved DATABASE_URL first. .env.local, other env files, or an enabled secrets provider like Doppler or Infisical can override it and point Prisma at an older database than the one you intended.

npx prisma db seed

The seed script does more than create the first admin. It also populates the initial catalog and baseline app data, including seeded plans, default settings, and the starter editable site pages the admin UI expects. In an interactive terminal, it prompts you for the admin email and password. For CI or automation, set SEED_ADMIN_PASSWORD and optionally SEED_ADMIN_EMAIL as environment variables to skip the prompt.

The password must satisfy the shared password policy from lib/password-policy.ts: at least 8 characters, with one uppercase letter, one lowercase letter, and one number. The prompt does not ask for password confirmation, so enter it carefully.

To skip admin creation entirely, run npx prisma db seed -- --skip-admin.

npm run demo:seed

Run this only after npx prisma db seed if you want the shipped admin and user dashboards to feel populated during local development. It adds demo users, organizations, subscriptions, payments, support tickets, notifications, visits, logs, and content so long lists and overview panels are easier to evaluate.

This is not a replacement for the normal Prisma seed and it should not be used as production or staging bootstrap data. Think of it as a local sandbox layer on top of the baseline app setup.

npm run dev

Open http://localhost:3000 to see the landing page. Sign in at /sign-in with the admin credentials you set during seeding, then visit /admin to explore the admin dashboard.

If you run local development on a custom domain such as https://app.localhost.test or through a tunnel URL, keep your URL env vars aligned with that host and set ALLOWED_DEV_ORIGINS so Next.js can serve dev assets to it.

A useful first stop is /admin/system, which gives you a live snapshot of maintenance mode, file storage, bearer-token readiness, webhook configuration, and email transport status.

The project uses Next.js route groups to keep admin and dashboard layouts isolated without changing the browser URL. If you see folders like (valid)in the file tree, that's a route group — it affects layout nesting but doesn't appear in the URL.

The name (valid) is a repo convention, not a special Next.js keyword. It simply groups routes that sit inside the main authenticated app shell. You can rename a route-group folder without changing the public URL, as long as the surrounding imports and layouts still line up.

The [...slug] catch-all files under app/admin/ and app/dashboard/ are fallback routes — they handle unmatched paths so the filesystem looks more complex than the actual URL structure.

Most of your custom product code goes in three places:

• app/dashboard/ — User-facing pages. Add new pages here for features your users interact with.
• components/ — React components. Use existing UI primitives from components/ui/ before creating new ones.
• lib/ — Business logic. Add your domain logic here, using the existing patterns for database access, validation, and error handling.