CLAUDE.md Template: Next.js + TS + Supabase + Clerk + Stripe + AI Docs for Document Management SaaS | CLAUDE.md template usage

Overview

The CLAUDE.md template is a copyable instruction block that guides Claude Code to generate, validate, and maintain a complete Document Management SaaS stack built with Next.js, TypeScript, Supabase, Clerk, Stripe, and AI features like document search, tagging, and summaries, with access control.

Direct answer: Paste the included CLAUDE.md block into your CLAUDE.md file to drive development of this stack.

When to Use This CLAUDE.md Template

• Starting a new DMS project with Next.js and TypeScript.
• Integrating Supabase as the backend and Clerk for authentication.
• Adding Stripe billing for subscriptions and webhooks.
• Implementing AI-powered document search, tagging, and automatic summaries.
• Enforcing robust access control and data security from day one.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are a Senior Full-Stack Engineer building a production-ready Document Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, and AI features for search, tagging, and summaries. Implement robust access control and auditability.

Architecture rules
- Use a modular monorepo with apps/web as the frontend and a clean backend contract with Supabase and Clerk.
- Frontend: Next.js with App Router, TypeScript, and server actions where appropriate.
- Backend: Supabase Postgres with RLS; Stripe for billing; use Clerk for authentication; AI search services via edge functions.
- Data flow: client requests → API routes → Supabase -> AI service wrappers; ensure minimal data exposure on the client.
- Logging and auditing: log critical actions to a secure audit log.
- Security: never expose secrets in client code; use Vercel/Secrets management; validate all inputs on server.

File structure rules
- Only include files and folders necessary to ship a DMS: pages or app routes, components, hooks, lib wrappers for 3rd party services, and AI service modules.
- Do not mix database migrations in the frontend; keep migrations in backend utilities.
- Use a consistent naming scheme: lowerCamelCase for files that export functions; PascalCase for components.

Authentication rules
- Clerk handles authentication; protect pages with requireAuth.
- Use server actions to read the current user and enforce permission checks server-side.
- Do not render user secrets or tokens on the client.

Database rules
- Supabase Postgres with Row-Level Security on documents, tags, and access_policies.
- Always store user_id from Clerk as the owner and creator.
- Define foreign keys for tags and documents; implement a document_audit table for actions.

Validation rules
- Use zod for all input validation; enforce schemas on server actions and API routes.
- Validate file types and sizes for uploads; limit AI results to sane lengths.

Security rules
- Protect API routes with auth middleware; never trust client-side validation alone.
- Use environment variables; do not hard-code keys.
- Implement rate limiting on AI search endpoints and webhook handlers.

Testing rules
- Unit tests for UI components with React Testing Library and Vitest.
- Integration tests for API routes using supertest or playwright tests for end-to-end flows.
- Mock external services (AI and payment) in tests; verify billing state transitions.

Deployment rules
- Deploy with Vercel or a similar platform; ensure Supabase migrations run during CI or manually.
- Configure Stripe webhooks; secure webhook endpoints.
- Set up environment-specific configs and secret rotation.

Things Claude must not do
- Do not bypass RBAC for any document action.
- Do not expose API keys or secrets on the client.
- Do not attempt direct DB edits from the frontend.
- Do not assume Prisma is present unless used; avoid unsupported libraries.

Recommended Project Structure

/
  apps/
    web/
      src/
        app/
        components/
        lib/
        services/
        styles/
      public/

Core Engineering Principles

• Type safety by default; opt out only with deliberate reasons.
• Security-first design and failure-aware thinking.
• Least privilege for all services; robust RBAC and audit trails.
• Clear separation of concerns between frontend, backend, and AI layers.
• Testability and repeatable deployments with CI/CD.

Code Construction Rules

• Frontend: implement components with strong props typing and strict TS checks.
• Backend: access control checks on all API routes and server actions.
• Database: define RLS policies; index common query fields (document_id, user_id, tags).
• AI: wrap calls to AI services; cache results and handle pagination for search results.
• Billing: handle Stripe checkout/session validation; verify webhook signatures.
• Logging: emit structured logs with correlation IDs for traceability.

Security and Production Rules

• Enable TLS, enforce secure cookies, and rotate keys regularly.
• Do not store secrets in the frontend; use environment variables and secret managers.
• Use server-side validation for all inputs and file uploads; implement content-type checks.
• Audit access to documents and financial events; expose only needed fields to the client.

Testing Checklist

• Unit tests for UI components and hooks; integration tests for API routes.
• End-to-end tests for creating, tagging, searching, and sharing documents.
• Pay attention to optimistic UI updates and error handling.
• Test Stripe webhooks and subscription lifecycle flows.
• Run security tests for RBAC policies and data exposure.

Common Mistakes to Avoid

• Not validating inputs on the server; rely on client validation alone.
• Overexposing tokens or API keys to the client.
• Skipping RBAC or forgetting to enforce RLS in queries.
• Ignoring audit logging for sensitive actions.

Related implementation resources: AI Agent Use Case for Chemical Suppliers Using Safety Databases To Instantly Provide Regulatory Compliance Documents To Clients and Why authorization checks belong in AI coding instructions for production-grade systems.

FAQ