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

Overview

Direct answer: This CLAUDE.md template provides a copyable Claude Code blueprint to build a complete AI Customer Support SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and RAG, with knowledge base upload and chat widget embedding. It is designed for production-grade apps and emphasizes maintainability, security, and scalable architecture.

The CLAUDE.md template below is stack-specific and ready to paste into a CLAUDE.md file. It enforces architecture, file structure, and deployment rules suitable for Claude Code guidance.

When to Use This CLAUDE.md Template

• When building a production AI customer support SaaS with the full stack: Next.js, TS, Supabase, Clerk, Stripe, RAG, knowledge base upload, and embeddable chat widget.
• When you require a copyable Claude Code instruction block to generate consistent scaffolding.
• When you need RBAC, secure storage of secrets, and end-to-end integration of commerce and knowledge graph.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are an expert AI architect who designs and enforces the architecture for a production-ready Next.js + TypeScript + Supabase + Clerk + Stripe + RAG AI Customer Support SaaS. You operate with Claude Code to produce maintainable, secure, and scalable code scaffolds.

Architecture rules:
- Platform: Next.js App Router (app directory) with TypeScript.
- Auth: Clerk integration for user management and auth flows; enforce RBAC (customer, agent, admin).
- Identity: Use Clerk for auth state; do not expose private keys in client bundles.
- Payments: Stripe integration for plans, subscriptions, and webhooks; verify webhook signatures server-side.
- Data & RBAC: Supabase Postgres with RLS; separate schemas for auth and data; strict policy checks on reads/writes.
- Search & knowledge: RAG pipeline using vector store (Supabase embeddings or external); knowledge base ingestion from uploads to storage and indexing.
- Embedding: Client chat widget shells embed a script; server validates origin; widget calls must be authenticated and scoped.
- Deployment: Use environment separation (dev/stage/prod) and secure secrets management; CI/CD with tests.

File structure rules:
- apps/web/src/app as primary Next.js 13+ directory
- Shared utilities under apps/web/src/lib
- Hooks and components under apps/web/src/components
- API routes under apps/web/src/app/api
- Infrastructure code must not mix frontend and backend concerns

Authentication rules:
- Use Clerk for all auth flows; require email verification for protected endpoints
- Use getAuth/session from Clerk on server routes to validate requests
- Implement role-based guards via server components or middleware
- Do not include secrets in frontend code

Database rules:
- Supabase Postgres with RLS enabled
- Tables: users, customers, agents, conversations, messages, knowledge_base, embeddings
- Use foreign keys: conversation -> customer, messages -> conversation
- Ensure policies allow only authorized users to read/write
- Validate inputs before insert/update

Validation rules:
- Use TypeScript types everywhere
- Apply Zod schemas on API boundaries
- Validate file uploads: mime type, size limit, and storage quotas
- Normalize and sanitize all user inputs

Security rules:
- Do not expose API keys to client
- Enforce CSRF protection for mutations
- Use signed URLs for file uploads
- Validate webhook signatures for Stripe
- Enable rate limiting on critical endpoints

Testing rules:
- Unit tests for utilities and endpoints
- Integration tests for auth flows, DB access, and chat endpoints
- End-to-end tests for signup, knowledge base upload, and chat flow
- CI workflow to run tests on PRs

Deployment rules:
- Environment variables for Clerk, Supabase, and Stripe
- Deploy via Vercel or compatible platform with edge functions
- Separate staging and production deployments
- Database migrations and seed scripts as needed (non-destructive)

Things Claude must not do:
- Do not expose secrets in frontend code
- Do not bypass server-side validation
- Do not rely on deprecated APIs
- Do not implement business logic beyond the scope of this template

Recommended Project Structure

my-ai-customer-support/
├─ apps/
│  └─ web/
│     ├─ src/
│     │  ├─ app/
│     │  │  ├─ layout.tsx
│     │  │  ├─ page.tsx
│     │  │  └─ api/
│     │  │     └─ hello/
│     │  ├─ components/
│     │  │  ├─ ChatWidget.tsx
│     │  │  └─ KnowledgeUploader.tsx
│     │  ├─ lib/
│     │  │  ├─ supabase.ts
│     │  │  ├─ clerk.ts
│     │  │  ├─ stripe.ts
│     │  │  └─ rag.ts
│     │  └─ hooks/
│     └─ next.config.js
└─ infra/
   └─ db/
      └─ migrations/

Core Engineering Principles

• Type safety first: TypeScript everywhere; define clear domain models.
• Security by default: RBAC, server-side validation, secret management, and signed webhooks.
• Separation of concerns: clear frontend/backend boundaries and small, composable modules.
• Reliability and observability: structured logging, metrics, and error handling.
• DX-friendly: copyable CLAUDE.md blocks and deterministic file layouts to aid reproducibility.

Code Construction Rules

• Frontend: Next.js App Router with TypeScript; server components and client components clearly separated.
• Auth: Clerk integration; use Clerk middleware for protected routes; store user roles in a dedicated table.
• Database: Supabase Postgres with RLS; enforce policies; use encrypted storage keys via environment vars.
• RAG: Vector embeddings stored in Supabase or chosen vector store; implement retrieval with cosine similarity; cache results in memory for latency.
• Knowledge base: Ingest uploaded documents to storage; extract text, chunk into segments, vectorize, and index.
• Chat widget: Provide a web widget script that authenticates via API tokens validated on the server, allows embedding, and secure cross-origin requests.
• Validation: Use Zod for all request validation; define explicit input schemas for every endpoint.
• Performance: Use ISR for non-dynamic pages; lazy-load heavy widgets; optimize images.
• Testing: Include unit, integration, and end-to-end tests; mock external services in unit tests.
• Deployment: Provide environment-specific configs; ensure deterministic builds; check for secret leakage in build logs.

Security and Production Rules

• Hide secrets in environment variables; never commit keys.
• Validate Stripe webhooks with signatures; reject invalid requests.
• Use signed URLs for uploads; enforce CORS restrictions for chat widget.
• RBAC on all APIs; require admin actions to be approved; audit logs for critical actions.
• Use rate limiting and input sanitization; protect against injection and XSS.

Testing Checklist

• Unit tests for utility functions and validators.
• Integration tests for auth flows, DB access, and chat endpoints.
• End-to-end tests for signup, knowledge base upload, chat conversation, and widget embedding.
• CI should run lint, type checks, tests, and build checks.

Common Mistakes to Avoid

• Over-privileging clients; keep secrets on the server.
• Skipping schema validation and RBAC on API boundaries.
• Using Prisma or non-Supabase DB layer unless it’s required.
• Ignoring webhook validation or insecure endpoints.
• Forgetting to seed or migrate the vector store during deployments.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Production-grade AI in regulated industries: practical templates and rules.

FAQ

What stack does this CLAUDE.md template cover?

Next.js, TypeScript, Supabase, Clerk, Stripe, RAG, knowledge base upload, and chat widget embedding.

How do I use the CLAUDE.md template?

Copy the block under “Copyable CLAUDE.md Template” into your CLAUDE.md file and customize config values.

What are the core rules Claude must follow?

Architecture rules, file structure, authentication, database, validation, security, testing, and deployment rules are explicitly defined in the CLAUDE.md block.

How is security handled in this template?

RBAC, server-side validation, CSRF protection, webhook signing, and secrets management are enforced.

How do I test this stack?

Unit tests for utilities, integration tests for auth/DB, and E2E tests for signup, knowledge base upload, and chat flow.