CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe — AI Research Assistant SaaS

Overview

CLAUDE.md template is a copyable blueprint for delivering a complete AI Research Assistant SaaS using the Next.js stack—Next.js with TypeScript, Supabase as the backend, Clerk for authentication, Stripe for billing, PDF upload, citation-based answers, and organized research collections. This page is a CLAUDE.md template page built for developers who want a drop-in Claude Code instruction block to guide implementation and governance for this stack.

Direct answer: This CLAUDE.md template provides a stack-specific, copyable CLAUDE.md block and concrete rules to drive development of a production-ready AI research assistant SaaS with the specified technologies. It is meant to be pasted directly into CLAUDE.md and followed by Claude Code execution.

When to Use This CLAUDE.md Template

• You are building a production-grade AI Research Assistant SaaS with Next.js, TS, Supabase, Clerk, Stripe, PDF uploads, and citation-based answers.
• You need a comprehensive, copyable CLAUDE.md block that enforces architecture, security, and deployment constraints for this stack.
• You want a clearly defined project structure and rules so Claude Code can produce consistent, auditable results.

Copyable CLAUDE.md Template

# CLAUDE.md
Project Role
- You are Claude Code, a production-grade assistant for building a complete AI Research Assistant SaaS on the following stack: Next.js, TypeScript, Supabase, Clerk, Stripe, PDF upload, citation-based answers, and research collections.

Architecture rules
- Use a Next.js 13+ App Router architecture with server components where appropriate.
- All API routes must be fully typed with TypeScript.
- Business logic must live in a libs/ or services/ layer with clear separation from UI code.
- All external calls must be parameterized, retrievable from environment variables, and audited.

File structure rules
- Maintain a clean, stack-specific layout:
  apps/web/
    app/
      layout.tsx
      page.tsx
      ...
    components/
    lib/
      supabase.ts
      clerk.ts
      stripe.ts
      pdf.ts
    services/
      auth.ts
      payments.ts
      citations.ts
      research.ts
  (Do not create non-relevant folders.)

Authentication rules
- Clerk must be the sole auth provider for end-user sessions.
- Implement role-based access: user, admin. Ensure endpoints check session and role.
- Never expose JWTs or API keys to the client.

Database rules
- Use Supabase Postgres with RLS enabled on all tables.
- Tables: users, papers, research_collections, citations, invoices, payments, pdfs, events.
- Use foreign keys and constraints; enforce data types and length constraints.

Validation rules
- Validate inputs with a strict schema (e.g., Zod) on both server and client sides.
- Normalize and sanitize all user-provided content before storage or display.

Security rules
- Never embed secrets in client bundles.
- Use SSL, protect API routes, and implement CSRF protection for state-changing endpoints.
- Enforce least-privilege access for services and API keys.

Testing rules
- Unit tests for services and utilities; integration tests for auth/login/payment flows; end-to-end tests covering PDF upload, citation generation, and research collection CRUD.
- Use Vitest for unit tests and Playwright for E2E.

Deployment rules
- Deploy on Vercel with CI checks; set env vars: SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_FRONTEND_API, CLERK_API_KEY, STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, NEXTAUTH_SECRET, NEXTAUTH_URL.
- Enable automatic type checking and linting in CI.

Things Claude must not do
- Do not bypass authentication or store credentials in logs.
- Do not assume data formats; validate all inputs.
- Do not propose unsafe coding patterns (like eval, insecure query patterns).
- Do not reference internal secrets in the CLAUDE.md output.

Recommended Project Structure

apps/web/app/layout.tsx
apps/web/app/page.tsx
apps/web/components/
apps/web/lib/supabase.ts
apps/web/lib/clerk.ts
apps/web/lib/stripe.ts
apps/web/lib/pdf.ts
apps/web/services/auth.ts
apps/web/services/payments.ts
apps/web/services/citations.ts
apps/web/services/research.ts
apps/web/styles/global.css

Core Engineering Principles

• Define a single source of truth for data models and access patterns.
• Keep Claude Code execution deterministic with explicit constraints and validations.
• Design for testability: unit, integration, and E2E coverage.
• Secure by default: enforce RBAC, RLS, and environment isolation.
• Prefer explicit over implicit and minimize dependencies on unsafe libraries.

Code Construction Rules

• All business logic goes behind typed services; UI uses only exposed APIs.
• Queries must be parameterized; never concatenate user input into SQL.
• Use server components for data fetching; client components only for UI state.
• Document API endpoints and their contracts in a central place.
• Lint and format with pre-commit hooks; maintain consistent naming conventions.

Security and Production Rules

• Enable Supabase RLS with per-user policies for sensitive data.
• Rotate keys; never commit secrets; use environment-based configuration.
• Audit logs for critical actions (payments, PDF uploads, citations creation).
• Implement CSRF protection for state-changing endpoints.

Testing Checklist

• Unit tests for utilities and service functions.
• Integration tests for auth, payments, PDf upload, and citations.
• End-to-end tests for user journeys: signup, login, file upload, citation query, and collection management.
• CI runs include type checks and linting.

Common Mistakes to Avoid

• Overloading client with server logic; keep server responsibilities on the server.
• Ignoring RBAC/RLS; assume all users can access all data.
• Storing secrets in code or logs; use secure vaults and env vars.
• Skipping validation and data normalization in either API or UI.

FAQ

Related implementation resources: AI Use Case for Podcasters Using Riverside.Fm To Instantly Generate Social Media Text Clips From Recorded Interviews and Using Skill Files to Stop SQL Injection in Generated Backend Code.