CLAUDE.md Template for Next.js TypeScript Invoice SaaS with Supabase Clerk Stripe

Overview

A CLAUDE.md template for building a complete Invoice Management SaaS using Next.js (App Router), TypeScript, Supabase, Clerk, Stripe, AI invoice extraction, PDF generation, and payment tracking. It includes concrete Claude Code blocks you can paste into CLAUDE.md to bootstrap the stack with production-ready defaults and guardrails.

Direct answer style summary: This CLAUDE.md Template provides a ready-to-paste Claude Code block and explicit rules to implement end-to-end invoicing features across a modern Next.js + TS + Supabase + Clerk + Stripe stack with AI extraction and PDF output.

When to Use This CLAUDE.md Template

• You are building a full Invoice Management SaaS with client dashboards, invoicing, and payments.
• You want AI-powered invoice data extraction to parse PDFs or images and populate structured data.
• You need end-to-end Stripe integration with secure webhooks and payment tracking.
• You prefer a Next.js App Router architecture with server components and clear separation of concerns.
• You require production-grade security, validation, and testing rules baked into the template.

Copyable CLAUDE.md Template

# CLAUDE.md

Project: Invoice Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, AI invoice extraction, PDF generation, and payment tracking

Role: You are Claude Code, a specialized assistant that outputs production-ready Claude Code blocks for the given stack. Your output must be directly pasteable into a CLAUDE.md file.

Stack: Next.js App Router, TypeScript, Supabase, Clerk, Stripe, AI invoice extraction, PDF generation, payment tracking

Architecture rules:
- Build a modular, testable, and secure multi-tenant SaaS architecture.
- Use Next.js App Router with server components for data access and client components for UI.
- Use Supabase for database, authentication, and storage; Clerk for user management only where required.
- Use Stripe for payments; webhook verification; handle idempotency.
- Leverage AI invoice extraction for field parsing; integrate via API route.
- Ensure CI/CD with Vercel or similar, and environment variables isolated.

File structure rules:
- Use /src/app structure with feature folders under /invoices.
- Keep concerns separate: components, hooks, lib, services, and ai modules.
- Do not place business logic in UI components.

Authentication rules:
- Use Clerk for user sign-in; enforce roles: admin and user.
- Use server actions to handle protected operations.
- Do not trust client-only validation; enforce server-side checks.

Database rules:
- Use PostgreSQL (Supabase) with tables: users, customers, invoices, invoice_lines, payments, events, audit_logs.
- Use row-level security; policies for read/write per role; enforce tenant isolation.
- Use numeric currency amounts in cents; store currency as ISO code.

Validation rules:
- Validate input shapes with Zod schemas.
- Invoices: status in {draft, sent, paid, overdue}; dueDate required for non-draft; totals computed from lines.
- Stripe webhook events validated with signature.

Security rules:
- Never log secrets; store tokens in environment variables.
- Use SSR for sensitive operations; avoid exposing private keys to the client.
- Validate all user actions on server; enforce least privilege.

Testing rules:
- Unit tests for utils and validators (Vitest).
- Integration tests for invoice lifecycle via API routes (Playwright or Cypress).
- End-to-end tests cover sign-in, create invoice, upload PDF, and payment status.

Deployment rules:
- Deploy to Vercel with environment variables: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE, CLERK_FRONT_END_API, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, AI_EXTRACTOR_API_KEY.
- Use webhooks securely; configure Stripe test and live modes.
- Run tests in CI; fail on flaky tests; store artifacts.

Things Claude must not do:
- Do not expose secret keys in code blocks.
- Do not bypass server-side validation.
- Do not hard-code production data.
- Do not rely on client-only authentication.
- Do not propose non-idiomatic or unsafe patterns.

Recommended Project Structure

invoice-saas/
├─ apps/
│  └─ web/
│     └─ src/
│        └─ app/
│           ├─ layout.tsx
│           ├─ page.tsx
│           ├─ invoices/
│           │  ├─ page.tsx
│           │  └─ [invoiceId]/
│           │     └─ page.tsx
│           └─ api/
│              └─ payments/
│                 └─ route.ts
│        ├─ components/
│        ├─ lib/
│        │  ├─ supabase.ts
│        │  ├─ stripe.ts
│        │  ├─ clerk.ts
│        │  └─ pdf.ts
│        └─ ui/
├─ infra/
│  └─ db/
│     └─ migrations/
└─ tools/
   ├─ scripts/
   └─ tests/

Core Engineering Principles

• Type-safe contracts: strong TypeScript types across API routes and UI components.
• Single source of truth: model invoices and payments via a well-defined schema on Supabase.
• Security-first: server-side validation, strict RBAC, and signed webhooks.
• Idempotent operations: all external effects (webhooks, payments) are idempotent.
• Observability: structured logs, events, and metrics for debugging and audits.

Code Construction Rules

• Prefer server components for data access; keep client components lean.
• Use Zod for input validation; share schemas between client and server when possible.
• All database access via server actions or API routes with strict access checks.
• Canonical data flow: API routes -> services -> database; UI consumes via typed fetch hooks.
• Do not perform secret operations on the client; secrets live in environment variables.
• Respect Stripe; generate invoices and payments with explicit idempotency keys.

Security and Production Rules

• Store secrets in environment variables and never expose them to the client.
• Validate all Stripe webhooks using the signed secret; verify event types and IDs.
• Implement RBAC: admin can manage tenants; users can only view their data.
• Protect API routes with server-side auth checks; perform authorization before data access.
• Enable HTTPS, CSP, and secure cookies; rotate keys periodically.

Testing Checklist

• Unit tests for validators, utils, and service helpers.
• Integration tests for invoice lifecycle (create, send, pay, reconcile).
• Webhook validation tests for Stripe events.
• End-to-end tests for sign-in, invoice creation, PDF generation, and payment flow.
• CI should run tests, lint, and type checks on every PR.

Common Mistakes to Avoid

• Do not bypass server-side validation; rely on client side validation only for UX, not security.
• Do not hard-code secrets or sample production data.
• Do not mix business logic with UI layer; keep services isolated.
• Do not neglect RBAC and tenant isolation in multi-tenant scenarios.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ

Q: What is a CLAUDE.md Template?
A: A copyable Claude Code block with stack-specific rules to bootstrap a project.

Q: Which stack is covered by this template?
A: Next.js App Router with TypeScript, Supabase, Clerk, Stripe, AI invoice extraction, and PDF generation.

Q: How do I use the Copyable CLAUDE.md Template block?
A: Copy the block under Copyable CLAUDE.md Template and paste into your CLAUDE.md file to bootstrap the project.

Q: What is the recommended project structure for this stack?
A: A Next.js 14+ App Router app with a clear invoices feature surface, lib/services for integrations, and API routes for data access.

Q: What security and deployment practices are required?
A: Use Clerk for auth, verify Stripe webhooks, protect server routes, and deploy with CI tests and secret rotation.