CLAUDE.md Template for Next.js + TypeScript + Supabase + Clerk + Stripe: Exam Preparation SaaS

Overview


CLAUDE.md template is a copyable Claude Code instruction block designed to guide you through building a complete Exam Preparation SaaS using Next.js (App Router), TypeScript, Supabase as the database, Clerk for authentication, Stripe for payments, and AI-driven quizzes with adaptive practice and progress dashboards. Direct answer: use this template to rapidly scaffold architecture, data models, integration points, and deployment rules for the stack, with precise Claude Code blocks you can paste into CLAUDE.md.




When to Use This CLAUDE.md Template



  - Starting a new SaaS project with the Next.js + TypeScript + Supabase stack and need standard architecture rules.

  - Integrating Clerk authentication, Stripe billing, and an AI-driven quiz engine with adaptive practice.

  - Producing a repeatable CLAUDE.md that teams can paste into CLAUDE.md to guide implementation from scaffolding to deployment.

  - Enforcing security patterns, testing strategies, and deployment rules from day one.



Copyable CLAUDE.md Template


Copy this Claude Code block into a CLAUDE.md file at the project root to generate the targeted boilerplate and implementation guidance.


# CLAUDE.md

Project role:
- You are a senior software engineer responsible for delivering a production-grade Exam Preparation SaaS built with Next.js (App Router), TypeScript, Supabase, Clerk, Stripe, AI quizzes, adaptive practice, and progress dashboards. Output must be Claude Code instructions for automating setup, wiring, and rule enforcement.

Architecture rules:
- Use Next.js App Router with server components for data-heavy paths (dashboard, analytics) and client components for UI. Ensure clear separation between UI, domain, and data access layers.
- Supabase is the single source of truth for data (users, exams, quizzes, questions, attempts, progress, payments, subscriptions, AI quiz caches).
- Clerk handles authentication and user roles; enforce session authentication on protected API routes and server actions.
- Stripe handles subscriptions and payments; implement idempotent webhook handlers; verify webhook signatures; store customer IDs and subscription state.
- AI quizzes and adaptive practice must run as serverless functions or microservices; cache AI-generated content and results; ensure prompt templates are versioned.
- Progress dashboards derive from normalized data in Supabase; implement reactive queries to avoid client-side duplication of state.
- Do not reveal secret keys on the client side; use environment variables and runtime config.

File structure rules:
- apps/portal/app/
  - layout.tsx
  - page.tsx
  - dashboard/
  - exams/
  - quizzes/
- apps/portal/components/
- apps/portal/lib/
- apps/portal/services/
- apps/portal/types/
- data/supabase/
- data/policies/
- scripts/

Authentication rules:
- Use Clerk for sign-in/up; require authentication for all protected routes (dashboard, exams, payments).
- Enforce role checks (admin, teacher, student) where applicable; store roles in Supabase and reflect in Clerk claims.
- Ensure CSRF protection for form submissions in server components.

Database rules:
- Tables: users, exams, quizzes, questions, attempts, progress, payments, subscriptions, adaptive_rules, ai_quiz_cache, analytics_events.
- Primary keys, foreign keys, and appropriate indices for queries used by dashboards and AI quizzes.
- Validate inputs via server-side schemas; never trust client-provided IDs for operations.

Validation rules:
- All API inputs/outputs validated with Zod schemas; consistent error response formats.
- Validate authorization claims on protected routes.

Security rules:
- Never expose secrets in client bundles; read from environment at runtime.
- Verify Stripe webhook signatures using the provided secret.
- Use server-side API routes for data mutations; avoid direct DB writes from the client.
- Implement rate limiting on sensitive endpoints.

Testing rules:
- Unit tests with Vitest for core utilities and data validation.
- Integration tests for API routes involving Supabase and Clerk.
- End-to-end tests with Playwright for login, quiz flow, and dashboard.
- Stripe webhook test events in staging.

Deployment rules:
- Deploy to Vercel with serverless functions enabled; configure environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_FRONTEND_API, STRIPE_WEBHOOK_SECRET, STRIPE_API_KEY.
- Enable Preview Deployments for feature branches; monitor via logs and error tracking.

Things Claude must not do:
- Do not bypass authentication or expose admin credentials; do not hard-code secrets; do not assume client can access privileged endpoints.
- Do not implement client-side AI prompt generation without caching or server-side evaluation.



Recommended Project Structure


Stack-specific directory tree for a Next.js + TypeScript + Supabase + Clerk + Stripe SaaS with AI quizzes and dashboards.


apps/portal/
  app/
    layout.tsx
    page.tsx
    dashboard/
      page.tsx
    exams/
      [examId]/page.tsx
    quizzes/
      [quizId]/page.tsx
  components/
  lib/
  services/
  types/
  pages/
  styles/
  data/
    supabase/
      schema.sql
      seeds.sql
  scripts/


Core Engineering Principles



  - Type safety everywhere: use TypeScript and strict Zod schemas for all IO.

  - Single source of truth: Supabase is the canonical data store; cache layer is read-only and invalidates on mutations.

  - Security by design: least privilege, server-side secrets, and verified webhooks.

  - Observability: structured logging, metrics, and tracing for API routes and background jobs.

  - Resilience: idempotent operations, retries with backoff, and clear failure modes.



Code Construction Rules



  - Adopt Next.js App Router conventions; separate routes into /dashboard, /exams, /quizzes.

  - Use React Server Components for data-heavy UI; client components for interactive widgets.

  - All API endpoints must be typed with Zod; return standard error formats.

  - Data access through a central service layer; avoid direct DB code in UI components.

  - Use Supabase JS client with auth session attachment for client calls; server components should validate session server-side.

  - Prompt templates for AI quizzes must be versioned and stored in Supabase; cache AI results with TTL.



Security and Production Rules



  - Store secrets in environment variables; never log them.

  - Verify Stripe webhooks with signatures; store webhook event IDs to prevent duplicates.

  - Protect admin endpoints with Clerk roles; enforce authorization checks in server actions.

  - Use CSRF protections for forms used in authenticated areas.

  - Limit file uploads and ensure validation to prevent injection attacks.



Testing Checklist



  - Unit tests for utilities, validators, and data mappers.

  - Integration tests for Clerk auth flows and Supabase data mutations.

  - End-to-end tests covering login, exam selection, AI quiz flow, adaptive practice, and dashboard rendering.

  - Stripe webhook dispatch tests with mock events; ensure idempotent processing.

  - Deployment smoke tests post-release in staging.



Common Mistakes to Avoid



  - Mixing client and server concerns; avoid performing privileged data fetches on the client.

  - Ignoring authentication on API routes; ensure all protected routes verify Clerk sessions.

  - Hard-coding secrets in code or commits; use environment-based configuration only.

  - Over-fetching data; curate API responses and paginate or window results for dashboards.



Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps.





FAQ



  - 
    What is a CLAUDE.md template for this stack?
    A copyable Claude Code instruction block that guides implementing a Next.js + TS + Supabase + Clerk + Stripe SaaS with AI quizzes, adaptive practice, and dashboards.


  

  - 
    Which tech stack does this CLAUDE.md Template cover?
    Next.js (App Router) with TypeScript, Supabase as DB, Clerk for auth, Stripe for payments, AI quizzes, adaptive practice, and dashboards.


  

  - 
    How do I use the copyable CLAUDE.md Template block?
    Copy the code block under Copyable CLAUDE.md Template into a CLAUDE.md file at your repo root, then run Claude to generate scaffolding and enforcement rules.


  

  - 
    What security considerations are included?
    Server-side secrets handling, Stripe webhook verification, authenticated API routes, and CSRF considerations for forms.


  

  - 
    What is the recommended deployment?
    Deploy to Vercel or a similar serverless host; configure environment vars and Stripe/Clerk webhooks; monitor with logs and error tracking.