CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe Course Marketplace

Overview

Direct answer: This CLAUDE.md Template provides a complete Next.js + TypeScript + Supabase + Clerk + Stripe stack for building a production-grade Course Marketplace with AI-assisted course generation, video lessons, certificates, and an instructor dashboard. It includes architecture rules, file structure, authentication and data schemas, validation, security, testing, and deployment guidance for Claude Code to generate a runnable scaffold.

This template targets a full-stack marketplace where course creators can publish AI-generated courses, learners enroll via Stripe, view video lessons, and receive certificates. It uses Next.js (App Router), TypeScript, Supabase for data and auth, Clerk for user management, and Stripe for payments. Claude Code can paste this template to generate a project skeleton with the described stack and features.

When to Use This CLAUDE.md Template

• You need a production-ready course marketplace scaffold with end-to-end auth and payments.
• You want AI-generated courses and quizzes integrated into the catalog.
• You require video lesson playback, certificate issuance, and an instructor dashboard.
• You are adopting a modern Next.js app-router architecture with TS strict mode.
• You prefer a clean, maintainable file structure and enforce security-at-design principles.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are a Claude Code assistant tasked with generating a production-ready Course Marketplace scaffold using Next.js, TypeScript, Supabase, Clerk, Stripe, AI course generator, video lessons, certificates, and an instructor dashboard. The output must be a runnable project skeleton with clear file structure, types, and security rules.

Architecture Rules:
- Use Next.js App Router with TypeScript and strict mode.
- Use Supabase for auth, data storage, and storage, with Row-Level Security (RLS).
- Use Clerk for user management and multi-factor authentication where required.
- Use Stripe for checkout and subscriptions; store payment intents and customer IDs in Supabase.
- Include an AI course generator microservice or integration (callable via API) to create course content and metadata.
- Store video lesson references (external hosting or embedded player) and keep metadata in Supabase.
- Provide an instructor dashboard with CRUD for courses, modules, lessons, and certificates.
- Ensure environment-specific configuration is externalized via env vars; never commit secrets.
- Do not rely on Prisma or other ORM unless explicitly required by the stack.
- Maintain accessible, responsive UI with proper error handling.

File Structure Rules:
- src/app/ for routes and app router structure
- src/components/ for reusable components
- src/lib/ for utilities, API clients (Supabase, Clerk, Stripe)
- src/lib/db.ts for database access and RLS policies documentation
- src/pages is deprecated in favor of app/ but can be used for legacy routes
- src/server/ for server actions and API routes
- public/ for static assets (logos, icons)
- tests/ for unit/integration tests
- .env.local.example with required keys (NEXT_PUBLIC_*, SUPABASE_* etc.)

Authentication Rules:
- Use Clerk for user accounts; sessions managed with secure cookies and JWTs
- Protect pages with requireAuth pattern; role-based access for instructors vs students
- Enforce MFA for instructor accounts
- Do not expose private API keys to the client

Database Rules:
- Supabase Postgres with RLS enabled on all tables
- Core tables: users, courses, modules, lessons, enrollments, instructors, certificates, purchases, ai_generated_content
- Use foreign keys with ON DELETE CASCADE where appropriate; use proper indices for fast queries
- Avoid storing plain secrets; use Vault or KMS for sensitive data

Validation Rules:
- Validate payloads server-side in API routes; client-side validation is supplementary
- Use Zod for schema validation and type-safe inputs
- Enforce required fields: course title, description, price, currency, instructorId, syllabus

Security Rules:
- Never expose database credentials client-side
- Use CSRF protection for state-changing operations
- Enable Content Security Policy (CSP) and set proper CORS
- Sanitize user input to prevent XSS
- Enforce rate limits on critical endpoints

Testing Rules:
- Unit tests for utility functions and validators
- Integration tests for booking flow, enrollment, and content generation
- End-to-end tests for instructor dashboard flows (Playwright/TestCafe)
- CI should run type checks (tsc) and linting (eslint) on PRs

Deployment Rules:
- Deploy to Vercel or a similar platform supporting Next.js
- Use environment-specific configs; ensure SUPABASE_URL/SUPABASE_ANON_KEY and CLERK_FRONTEND_API etc. are set in the environment securely
- Automate migrations and seed data via a migrations script if needed
- Monitor with logging and error tracking (e.g., Sentry)

Things Claude Must Not Do:
- Do not hardcode secrets or credentials
- Do not bypass authentication or authorization checks
- Do not generate server-side code that exposes database admin endpoints
- Do not assume Prisma is in use unless explicitly required
- Do not create insecure endpoints or bypass rate limits

Recommended Project Structure

src/
  app/
    api/                 # API routes if needed, otherwise use app router
    instructors/         # instructor dashboard routes
    courses/             # course catalog and course pages
    payments/            # Stripe/webhook handlers and checkout pages
    ai-generator/        # AI course generator integration
  components/            # React components shared across pages
  lib/
    supabase.ts          # Supabase client and helpers
    clerk.ts             # Clerk client helpers
    stripe.ts            # Stripe client helpers and checkout async actions
  models/                 # TypeScript interfaces for domain data
  pages/                  # optional legacy routes (if any)
  styles/                 # CSS/SCSS
  tests/                  # unit/integration tests
  public/                 # static assets (logos, icons)

Core Engineering Principles

• Type safety and strict TS across the stack; define clear domain models.
• Security by design: enforce authentication, authorization, and data validation at the API boundary.
• Separation of concerns: UI, business logic, and data access are clearly separated.
• Scalability: modular architecture and lazy loading where appropriate.
• Observability: structured logging and error reporting; telemetry for critical paths.

Code Construction Rules

• Use Next.js App Router with TypeScript strict mode.
• Use Supabase for auth and data; enable RLS on all tables and document policies.
• Clamp API surface: authenticate requests and enforce role-based authorization.
• Validate inputs with Zod on both client and server sides.
• Keep secrets in environment variables; do not commit keys.
• Do not use Prisma unless explicitly requested; prefer Supabase DB client patterns.
• Prefer server components for data fetching; client components only where needed.

Security and Production Rules

• Enable CSRF protection for API routes and server actions consuming state-changing data.
• Implement strict CSP and secure cookies; set HTTPOnly, Secure, SameSite attributes.
• Regularly rotate API keys and secrets; monitor for anomalous activity.
• Use proper input sanitization and output escaping to prevent XSS/SQL injection.
• Implement rate limiting on sensitive endpoints like content generation and checkout.

Testing Checklist

• Unit tests for utility functions and validators with high coverage.
• Integration tests for auth flows (Clerk), enrollment, and checkout (Stripe).
• End-to-end tests for instructor dashboard operations (Playwright).
• Performance checks for AI content generation path.
• CI runs type checks and linting on every PR.

Common Mistakes to Avoid

• Hardcoding secrets or API keys in code or markdown templates.
• Relying on client-side validation alone for critical operations.
• Neglecting SRL policies in Supabase; ensure proper RLS coverage.
• Overcomplicating data models; start lean and iterate with AI-generated content.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ