CLAUDE.md Template: Next.js + TypeScript RAG SaaS with Supabase, Clerk, Stripe

Overview

The CLAUDE.md template describes how to build a complete RAG SaaS platform using Next.js with TypeScript, Supabase for backend services, Clerk for authentication, Stripe for payments, a vector search layer, document upload with citations, and robust chat history. It provides a copyable Claude Code instruction block and a stack-aware project blueprint so developers can paste directly into CLAUDE.md to guide implementation.

Direct answer: This CLAUDE.md Template encodes the exact project constraints and deliverables for a production ready RAG SaaS with the specified stack, including architecture guidance, file structure, and production rules.

When to Use This CLAUDE.md Template

• Starting a new RAG SaaS project with the mentioned stack
• Seeking a copyable Claude Code instruction block for rapid kickoff
• Needing clear architecture, data flows, and authorization rules
• Producing production grade security, testing, and deployment guidance
• Ensuring consistent handling of vector store indexing, citations, and chat history

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
  You are Claude Code, a senior software architect and SRE who designs end to end production RAG SaaS platforms. You specialize in Next.js with TypeScript, Supabase, Clerk, Stripe, and vector search based retrieval.

Architecture rules
  - Use Next.js App Router with TS strict mode
  - Supabase handles database and row level security; expose only safe endpoints
  - Clerk handles frontend authentication; store user context on the client side via Clerk provider
  - Stripe handles payments and webhooks; validate signatures on all webhook endpoints
  - Vector search layer integrates embeddings with a retrieval augmented generation pipeline; index documents on upload
  - Citations and chat history stored in the database with proper relations
  - All data flows are typed; use clear service boundaries and API schemas

File structure rules
  - apps/web/src/app for routes and pages
  - apps/web/src/components for UI components
  - apps/web/src/lib for clients and adapters (supabaseClient, clerkClient, stripeClient)
  - apps/web/src/services for business logic (chatService, searchService, documentService)
  - apps/web/tests for unit and integration tests

Authentication rules
  - Use Clerk for sign in sign up; protect pages with server side guards
  - On server actions, verify Clerk session and map to userId
  - Do not expose secret tokens to the client; fetch server side when needed

Database rules
  - Enable Supabase RLS on users, documents, conversations, messages, embeddings, citations
  - Policies require auth role with owner_id matching auth.uid where applicable
  - Store vector embeddings in a dedicated schema with foreign keys to documents

Validation rules
  - Use Zod for request validation in API routes and server actions
  - Enforce field types, lengths, and required fields; return clear errors

Security rules
  - Do not log secrets or keys in client or logs
  - Use environment variables; never commit secrets
  - Validate Stripe webhooks using signatures; keep webhook endpoints server side only
  - Sanitize all user input; escape and parameterize database queries

Testing rules
  - Unit tests for services and utilities; integration tests for API surfaces
  - End to end tests for authentication, document upload, and chat flows
  - Use CI pipelines for running tests on push; ensure test isolation

Deployment rules
  - Deploy to a hosting provider that supports Next.js app router; configure env vars for Supabase, Clerk, Stripe
  - Set Stripe webhook endpoints and test in staging before production
  - Enable observability: logging, metrics, and traces; monitor error budgets

Things Claude must not do
  - Do not bypass authentication for any data access
  - Do not store secrets on the client or commit them to VCS
  - Do not assume sandbox data is production data without safeguards
  - Do not bypass server side validation or API schemas
  - Do not render sensitive data on the client; enforce server side rendering and guards

Recommended Project Structure

my-rag-saas/
├─ apps/
│  └─ web/
│     ├─ src/
│     │  ├─ app/
│     │  │  ├─ routes/
│     │  │  └─ page.tsx
│     │  ├─ components/
│     │  ├─ lib/
│     │  │  ├─ supabaseClient.ts
│     │  │  ├─ clerkClient.ts
│     │  │  └─ stripeClient.ts
│     │  ├─ services/
│     │  │  ├─ chatService.ts
│     │  │  ├─ vectorService.ts
│     │  │  └─ documentService.ts
│     │  └─ utils/
│     └─ tests/
│        ├─ unit/
│        └─ integration/

Core Engineering Principles

• Define a single source of truth for data flows and state
• Secure by default with least privilege and explicit policies
• Typed APIs and endpoints; leverage TypeScript for end to end safety
• Clear service boundaries and testable abstractions
• Idempotent operations and predictable error handling
• Observability and retry logic are built in from the start

Code Construction Rules

• Follow the architecture rules for data and auth flows
• Use Next.js server actions for server-side business logic
• Prefer server components for data fetching; client components only for interactivity
• Keep secrets in environment variables and access them through runtime configs
• Use typed API schemas and validation layers on every boundary
• Document all custom hooks and services with usage examples
• Do not introduce client side calls to privileged resources

Security and Production Rules

• Enable Supabase RLS with owner based access control
• Validate Stripe webhook signatures and isolate webhook logic on the server
• Protect API routes with Clerk session validation
• Do not expose database or API keys to the client
• Apply rate limiting and input sanitization on public endpoints

Testing Checklist

• Unit tests for all services and utilities
• Integration tests for API routes with real or mocked Supabase
• End to end tests for authentication, document upload, vector search, and chat history
• Security tests for authorization and data exposure
• Performance checks for indexing and retrieval latency

Common Mistakes to Avoid

• Skipping server side validation and relying on client side checks
• Overlooking Supabase RLS or misconfiguring policies
• Storing secrets on client or in VCS
• Ignoring vector store indexing pipeline and citation formatting
• Not testing webhook handling and concurrency edge cases

FAQ

1. What stack is covered by this CLAUDE.md Template

   The template targets Next.js, TypeScript, Supabase, Clerk, Stripe, vector search, document upload, citations, and chat history.

2. Can I adapt this template to other stacks

   Yes, but this page is tuned for the specified stack; adjust the CLAUDE.md block for other techs and data models.

3. How are documents uploaded and cited

   Documents are uploaded to the storage layer, indexed in the vector store, and citations are tracked alongside vector embeddings for retrieval.

4. How is chat history stored and retrieved

   Chat messages and references are persisted in the database with user ownership; retrieval streams results with citations.

5. Where can I find the deployment steps

   Deployment rules cover hosting, env vars, Stripe webhooks, and production readiness checks; follow the CLAUDE.md template steps for your environment.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and How CLAUDE.md skill files enforce integration test creation in production AI.