CLAUDE.md Template for Next.js, TypeScript, Supabase, Clerk, Stripe AI PDF Chat SaaS

Overview

CLAUDE.md Template is a copyable instruction block for Claude Code to architect a production-ready AI PDF Chat SaaS stack using Next.js, TypeScript, Supabase, Clerk, and Stripe. It covers document collections, citations, highlights, and exportable answers. Direct answer: paste the CLAUDE.md template block below into CLAUDE.md and follow its rules to implement a complete end-to-end system.

When to Use This CLAUDE.md Template

• You are building an AI PDF chat SaaS with a modern frontend (Next.js) and a persistent backend (Supabase).
• You require robust authentication (Clerk) and payments (Stripe) in a single stack.
• You need document collections with citations, highlights, and exportable answers for end users or teams.
• You want a paste-ready CLAUDE.md that codifies architecture, data models, and deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are the AI systems architect for a production-ready AI PDF Chat SaaS built with Next.js, TypeScript, Supabase, Clerk, and Stripe. Your responsibilities include defining data models for documents, collections, citations, highlights, and exportable answers; shaping authentication and billing flows; and guiding deployment.

Architecture rules
- Use Next.js (App Router) with server components for data fetch and API routes for payments and webhooks.
- Persist data in Supabase Postgres; store PDFs, documents, citations, highlights, and exportable answers in clearly named tables.
- Integrate Clerk for authentication and user sessions; enforce RBAC with user roles (user, admin).
- Stripe handles subscriptions, invoices, and checkout; expose a secure webhook endpoint to reconcile state.
- All data access must go through typed, validated interfaces; never bypass server-side validation on the client.
- Favor server-side data fetching for personalized content; keep heavy UI logic on the client.

File structure rules
- Place the app under apps/web with a Next.js app router structure.
- Keep reusable business logic in lib/; separate services for Supabase, Clerk, and Stripe in services/.
- Create components/ and hooks/ for UI and composition; avoid ad-hoc snippets.
- Do not include unused folders (e.g., unnecessary monorepo scaffolding).

Authentication rules
- Implement ClerkProvider at the root and protect routes using auth guards; require an authenticated user to access PDF data.
- Enforce email verification and plan entitlement checks for paid features.
- Do not expose auth tokens to the client; fetch them server-side when needed.

Database rules
- Enable Supabase Row Level Security (RLS) on all tables; policy requires user_id match or is_admin.
- Tables: documents(id uuid, title text, content text, collection_id uuid, metadata jsonb), collections(id uuid, name text, user_id uuid), citations(id uuid, document_id uuid, reference text), highlights(id uuid, document_id uuid, snippet text), answers(id uuid, user_id uuid, content text, export_type text), users(id uuid, email text).
- Enforce NOT NULL on essential fields; add created_at/updated_at timestamps.

Validation rules
- Validate inputs with strong schemas (e.g., zod) for API payloads: document content length, citation format, export payloads, payment intent IDs.
- Validate user permissions before every data mutation.
- Sanitize inputs to prevent XSS in content and export outputs.

Security rules
- Never leak private keys or API secrets to the client; store in environment variables and fetch on server.
- Use CSRF protection on state-changing requests; verify Stripe webhooks signatures.
- Encrypt sensitive fields at rest if supported; minimize JWT lifetime; rotate keys.
- Do not hard-code secrets in code or commits.

Testing rules
- Unit tests for data validators (document, collection, citation, highlight, answer models).
- Integration tests for auth flows (Clerk), API endpoints (documents, collections, citations, highlights, answers), and Stripe webhooks.
- End-to-end tests for the signup, PDF upload, search, cite, highlight, and export flows.
- CI should run type checks, lint, tests, and a lightweight e2e test in a preview environment.

Deployment rules
- Target Vercel with Next.js; set environment variables for Supabase, Clerk, and Stripe.
- Configure Stripe webhooks in production; ensure endpoints are protected and validated.
- Enable serverless functions and edge caching where appropriate for latency-sensitive search.
- Set proper SSL, CORS, and content security policies; log to a centralized service with redaction.

Things Claude must not do
- Do not bypass Clerk authentication or access protected data without a valid session.
- Do not mutate payment state without a Stripe-confirmed event.
- Do not reveal secret keys or database credentials in the code or logs.
- Do not implement direct database queries from the client; route through server handlers with validation.

Recommended Project Structure

projects/
  apps/
    web/
      app/
        router.tsx
        layout.tsx
        pages/
      components/
      hooks/
      lib/
        supabaseClient.ts
      services/
        clerkService.ts
        stripeService.ts
      styles/
      public/
  db/
    schemas/
      documents.sql
      collections.sql
  scripts/
    deploy.sh
    seed.ts

Core Engineering Principles

• Clear ownership and accountability for data at every layer.
• Strong type safety across frontend and backend; use TypeScript consistently.
• Data-driven architecture with explicit contracts between services (Supabase, Clerk, Stripe).
• Secure by default: least privilege, proper authentication, and auditing.
• Idempotent operations for mutation endpoints and idempotent webhooks handling.
• Observability: structured logs, metrics, and tracing for critical paths.

Code Construction Rules

• Use the app directory with server components for data fetch; keep client components lean.
• Typed API routes with clear input validation (e.g., Zod) and explicit return types.
• All database mutations go through a service layer with access control checks.
• Document content, citations, and highlights stored in dedicated tables with FK constraints.
• Do not embed secrets or API keys in client code or CLAUDE.md templates.
• Prefer small, composable UI components with well-defined props.

Security and Production Rules

• Enable Supabase RLS; craft policies per user role and data scope.
• Use Clerk for authentication; guard routes and API handlers with server-side checks.
• Validate and verify Stripe webhooks; never trust client-submitted webhook payloads.
• Encrypt and mask sensitive data in logs; separate secrets with environment variables.
• Implement rate limiting on API routes that query large doc sets.

Testing Checklist

• Unit tests for validators, data models, and service layers.
• Integration tests for auth flows, document CRUD, and citation/highlight logic.
• End-to-end tests for sign-in, document upload, search, citation, highlight, and export.
• Deployment smoke tests in staging; verify Stripe webhooks and subscriptions.

Common Mistakes to Avoid

• Bypassing server validation or exposing raw database errors to the client.
• Overly broad RLS policies that leak data between users.
• Storing PDFs as large blobs without chunks or streaming support; use references and streaming if needed.
• Mixing UI and business logic in components; keep concerns separated.
• Forgetting to rotate secrets after deployment or in CI.

Related implementation resources: AI Use Case for Venues Using Past Electricity Bills To Predict Peak Utility Costs During Heavy-Production Trade Shows and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ

• How do I start using this CLAUDE.md Template? – Copy the CLAUDE.md block into CLAUDE.md and implement per the architecture rules for Next.js + TS + Supabase + Clerk + Stripe.
• What stack does this template cover? – Next.js (App Router) with TypeScript, Supabase, Clerk, and Stripe for an AI PDF Chat SaaS with document collections, citations, highlights, and exportable answers.
• How are documents and citations modeled? – Documents live in Supabase with citations and highlights tied to document IDs; exportable answers reference document content and citations.
• How do I deploy and secure this in production? – Deploy to Vercel, configure environment variables, set Stripe webhooks, enable Supabase RLS, and implement proper auditing.
• What should I not do in this template? – Do not expose secrets, bypass auth, or bypass data validation; avoid unsafe client-side mutations.