CLAUDE.md Template: Next.js TypeScript Supabase Clerk Stripe AI Report Generator SaaS

Overview

The CLAUDE.md template is a copyable blueprint for building a complete AI Report Generator SaaS stack using Next.js (App Router), TypeScript, Supabase for data storage, Clerk for authentication, Stripe for billing, plus data upload, narrative generation, charts, and PDF export. This template is tailored for Claude Code workflows and produces a production-ready CLAUDE.md that you can paste into your project. Direct answer: You get a ready-to-run blueprint that covers auth, data ingestion, AI-driven narrative, visualization, and export in a single cohesive pattern.

When to Use This CLAUDE.md Template

• You are building a multi-tenant SaaS with a modern Next.js frontend.
• You need secure authentication and billing with Clerk and Stripe.
• You require data upload flows, server-side validation, and database access via Supabase.
• You implement AI-driven narrative generation and charted visualizations with export to PDF.
• You want a repeatable CLAUDE.md that developers can copy-paste into a project.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude Code, an AI software architect assistant. Your job is to deliver a complete CLAUDE.md Template for a Next.js + TypeScript SaaS powered by Supabase, Clerk, and Stripe. Your output must be a single, copyable CLAUDE.md block that a developer can paste directly into a CLAUDE.md file.

Architecture rules
- Use Next.js 13+ App Router with TypeScript. Separate UI, domain, and infrastructure boundaries.
- Persist data in Supabase (Postgres) with Row-Level Security enabled. Use service roles only on server.
- Authenticate users with Clerk. Protect all user data with policy guards and server components.
- Billing with Stripe. Implement checkout sessions and webhooks securely; store customer IDs in a user profile.
- Implement an AI narrative engine as a server action / API route that queries a vector store or prompting layer as needed.
- All secrets must live in environment variables; never commit keys.
- Use a modular monorepo layout if multiple packages; keep environment parity across dev/stage/prod.

File structure rules
- apps/web for the Next.js frontend
- apps/web/src for source code (server and client components)
- apps/web/public for assets
- apps/web/next.config.js and tsconfig.json present
- libs/ or packages/ for shared code (utilities, API clients, UI components)
- supabase/ for database migrations and seed data
- scripts/ for deployment/maintenance scripts

Authentication rules
- Clerk handles user auth. Pages and APIs must check session status before rendering user data.
- Use server components with guard clauses; avoid passing auth tokens to the client.
- Enforce email/password + OAuth flows as configured in Clerk; support multi-factor if required.

Database rules
- Supabase with Postgres; enable RLS on every table.
- Create policies that scope data to the current user or tenant.
- Store audit logs for major actions (data upload, report generation, export).
- Validate inputs on the server; never trust client input.

Validation rules
- Use Zod schemas for all API inputs and server actions.
- Validate file uploads (types: CSV, Excel, JSON) and parse them deterministically.
- Normalize and sanitize all text to prevent injection vectors.

Security rules
- Never expose secrets to the client; use runtime config/env vars for keys.
- Harden CORS to allow only your frontend domains.
- Implement CSRF protection on state-changing endpoints.
- Use validated webhook endpoints for Stripe and Clerk.

Testing rules
- Unit tests with Vitest for utilities and API routes.
- Integration tests for data upload, authorisation flow, and report generation.
- E2E tests using Playwright or Cypress covering sign-in, data upload, narrative generation, chart rendering, and PDF export.
- Run tests on CI for PRs and on PR previews.

Deployment rules
- Deploy on Vercel or similar with production-grade environment variables.
- Ensure build-time secrets are provided via the platform.
- Create a reproducible DB migration plan and ensure zero-downtime migrations.
- Enable server-side rendering for critical pages; lazy-load heavy components.

Things Claude must not do
- Do not bypass Clerk authentication or expose an admin API key to the client.
- Do not hard-code secrets or credentials in code or CLAUDE.md.
- Do not assume a single-tenant database without proper RLS and tenant routing.
- Do not generate content that bypasses validation or security checks.
- Do not rely on client-side only data for critical authorization decisions.

Recap
- This CLAUDE.md block provides a shipping-ready blueprint for a Next.js + TS SaaS with Supabase, Clerk, Stripe, data upload, narrative AI, charts, and PDF export. Paste this into your CLAUDE.md file to start building.

Recommended Project Structure

/apps/web/
├─ next.config.js
├─ tsconfig.json
├─ package.json
├─ public/
├─ src/
│  ├─ app/                # Next.js App Router (pages and routes)
│  │  ├─ layout.tsx
│  │  ├─ page.tsx
│  │  ├─ dashboard/
│  │  └─ reports/
│  ├─ lib/                # API clients, helpers
│  ├─ components/         # UI components
│  ├─ services/           # Stripe, Clerk, Supabase wrappers
│  ├─ hooks/              # React hooks
│  └─ styles/
└─ 
/supabase/
├─ migrations/
├─ seed/
└─ schema.sql

/scripts/
- deploy.sh
- migrate.sh

.env.example

Core Engineering Principles

• Principle of explicit contracts: functions and API surfaces must have clear input/output types.
• Security first: guard all data with proper auth/authorization and never expose secrets.
• Single source of truth: centralize business rules in server components or API routes.
• Progressive enhancement: render critical data on server when possible; hydrate on client with minimal payload.
• Test everything: unit, integration, and end-to-end tests accompany every feature.

Code Construction Rules

• Use TypeScript end-to-end with strict mode enabled in tsconfig.json.
• All API inputs validated with Zod schemas; return well-typed responses.
• Supabase: enable Row Level Security; write policies for tenant isolation.
• Clerk: protect pages; use server components for authentication checks; never expose tokens to the client.
• Stripe: implement webhook signing verification; store customer_id and subscription_id safely.
• Data uploads: validate file types (CSV, XLSX, JSON); parse deterministically on server.
• Narrative generation: keep prompts deterministic; cache results per user/report to avoid duplicate calls.
• Charts: render on server when possible or with lightweight client rendering; export to PDF from server-side route.
• PDF export: offer a server-side rendering path that serializes charts and tables precisely.
• Do not rely on client-side secrets or direct database access from the browser.

Security and Production Rules

• Store all secrets in environment variables; never commit keys.
• Enable CORS only for your frontend domains.
• Use Stripe webhooks with signature verification; expose minimal endpoint surface.
• Enforce server-side rendering for sensitive dashboards and reports.
• Apply strict content security policy and proper CSP headers.
• Regularly rotate keys and review IAM policies for Supabase and Stripe connections.

Testing Checklist

• Unit tests for all utilities and API helpers (Vitest).
• Integration tests covering data upload, auth, and report generation flows.
• End-to-end tests for sign-in, data ingestion, narrative generation, charts rendering, and PDF export (Playwright).
• CI should run linting, type checks, and all tests on every PR.
• Performance checks for narrative generation latency and chart rendering times.

Common Mistakes to Avoid

• Ignoring Supabase RLS leading to data leakage across tenants.
• Embedding secret keys in client code or CLAUDE.md blocks.
• Over-reliance on client-side rendering for critical auth decisions.
• Skipping webhook signature verification for Stripe.
• Skipping validation on file uploads or failing to sanitize inputs.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Access control in routing layouts: practical AI-driven verification patterns for production systems.

FAQ

Q1: What stack does this template cover?

A1: Next.js (App Router) with TypeScript, Supabase for data storage, Clerk for authentication, Stripe for billing, plus data upload, narrative generation, charts, and PDF export.

Q2: How do I use the copyable CLAUDE.md block?

A2: Copy the entire CLAUDE.md block, paste into your CLAUDE.md file, and adjust project-specific identifiers and environment references.

Q3: How is data secured across tenants?

A3: Data is isolated via Supabase Row-Level Security policies; tenant context is enforced on server routes and API handlers.

Q4: How do I add a new data source?

A4: Extend the data ingestion service, add a new input schema in Zod, and update the narrative generation prompts to incorporate the new data fields.

Q5: Can I export reports to PDF with charts?

A5: Yes. The template includes a server-side path to render charts and content into a PDF export with deterministic layout.