CLAUDE.md Template for Next.js + TS + Supabase + Clerk + Stripe — Subscription Billing SaaS

Overview

CLAUDE.md template for building a complete Subscription Billing SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI revenue analytics, plan management, and churn prediction. This page provides a copyable CLAUDE.md template you can paste into Claude Code to bootstrap the stack with production-grade defaults.

When to Use This CLAUDE.md Template

• Use when you need end-to-end architecture for a SaaS billing solution with Stripe integration.
• Use when you want a production-ready Next.js (App Router) + TypeScript project backed by Supabase and Clerk.
• Use when you need AI-driven revenue analytics and churn prediction baked in.
• Use when you want a reproducible CLAUDE.md code block for rapid iteration.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior full-stack engineer building a production-grade Subscription Billing SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, with AI revenue analytics, plan management, and churn prediction. Your goal is to deliver a repeatable, secure, and scalable blueprint that Claude Code can implement deterministically. CLAUDE.md template

Architecture rules:
- Use Next.js App Router with server components for data access and client components for UI.
- Prefer a multi-tenant data model in Supabase; isolate tenant data by tenant_id with Row Level Security.
- Use Clerk for authentication and authorization; check user roles for access to billing resources.
- Use Stripe webhooks to sync subscriptions, invoices, and payments; validate webhook signatures server-side.
- Expose a minimal REST API via Next.js API routes or Edge Functions for integration with external services.
- Implement a separate analytics service boundary for AI revenue analytics.
- Use typed data contracts across frontend and backend (TypeScript types shared via a monorepo if possible).

File structure rules:
- app/ with layout.tsx and relevant route/* files
- src/lib/supabase.ts for client and server helpers
- src/lib/clerk.ts for authentication helpers
- src/lib/stripe.ts for payment integration
- modules/billing/, modules/plans/, modules/analytics/, modules/churn/
- components/ for reusable UI, hooks/ for hooks, services/ for business logic

Authentication rules:
- All billing APIs require an authenticated Clerk session; require a MinimalRole: billing_user or admin.
- Store user_id and tenant_id in sessions; use them to scope data access.
- Do not access Stripe keys in the client; route all Stripe calls through server-side code.

Database rules:
- Supabase Postgres with tables: tenants, users, customers, subscriptions, plans, invoices, revenue_events, churn_predictions.
- Enforce Row Level Security using policies tied to tenant_id.
- Use foreign keys and proper indices on tenant_id and subscription_id.

Validation rules:
- Validate all inputs with Zod; export types from a shared ts file.
- Validate webhook payloads against Stripe's signature.

Security rules:
- Do not log secrets or keys; use environment variables; mask sensitive fields in logs.
- Enable CORS selectively for trusted origins; deny by default.
- Keep Stripe keys in server-side env vars; never commit to repo.

Testing rules:
- Unit tests for core modules with Vitest.
- Integration tests for billing flow with test Stripe keys via Stripe's test mode.
- E2E tests (Playwright) for critical flows: signup, plan change, checkout, and churn dashboard.

Deployment rules:
- Deploy on a platform that supports server components (e.g., Vercel); create separate environments for dev/staging/prod.
- Set environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_FRONTEND_API, CLERK_SECRET_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET.
- Enable monitoring and error reporting in production.

Things Claude must not do:
- Do not hardcode secrets or keys.
- Do not implement client-side Stripe secret calls.
- Do not bypass authentication or tenant scoping.
- Do not assume a single tenant; design for multi-tenancy from day one.
- Do not use non-typed inputs; avoid unverified dynamic code.

Recommended Project Structure

apps/web/                        # Next.js app
  app/                          
    layout.tsx
    page.tsx
  components/
  hooks/
  styles/
src/
  lib/
    supabase.ts
    clerk.ts
    stripe.ts
  modules/
    billing/
    plans/
    analytics/
    churn/
  services/
  pages/

Core Engineering Principles

• Type safety and explicit contracts across frontend/backend
• Security-by-default with least-privilege access
• Server-first architecture using Next.js App Router
• Observability through structured logs, metrics, and tracing
• Testability with unit, integration, and E2E tests
• Deterministic builds and reproducible infrastructure

Code Construction Rules

• Use TypeScript everywhere; share types between client and server
• Implement Supabase data access behind server routes; never call DB directly from the client
• Use Clerk middleware for auth; protect sensitive endpoints
• Stripe integration via server-side code; verify webhooks
• Validate all inputs with Zod; export types for re-use
• Keep UI components lean; split heavy logic to services
• Do not rely on Prisma or other ORMs if not part of stack

Security and Production Rules

• Store secrets in environment variables; never commit to repo
• Enforce tenant isolation with Row Level Security
• Audit logging for sensitive operations (billing changes, payouts)
• Use Stripe webhooks with signature verification
• Regularly rotate keys and monitor for anomalous activity

Testing Checklist

• Unit tests for shared utilities and services
• Integration tests for billing, plans, and subscriptions
• E2E tests for signup, plan changes, checkout, and churn analytics
• Smoke tests on deployment previews

Common Mistakes to Avoid

• Hardcoding environment-specific values
• Exposing Stripe secret calls to the client
• Overcomplicating the data model for multi-tenancy
• Skipping webhook verification or logging of events

Related implementation resources: AI Use Case for Demolition Contractors Using Sensor Logs To Optimize Explosive Placement for Safe Building Implosions and Skill Files for PMs: Building Realistic Clickable SaaS Demos with CLAUDE.md Templates.

FAQ