CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe for AI Finance Analyst SaaS

Overview

The CLAUDE.md template describes how Claude Code should implement a complete AI Finance Analyst SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, with features for spreadsheet upload, anomaly detection, and executive reports. This page provides a copyable CLAUDE.md template you can paste into CLAUDE.md to bootstrap the project.

Direct answer: This CLAUDE.md Template is a drop-in blueprint for producing production-grade code and docs for a multi-tenant AI finance platform with secure auth, payments, data processing, and reporting.

When to Use This CLAUDE.md Template

• You're building a multi-tenant AI Finance Analyst SaaS with a Next.js frontend and a scalable backend.
• You require authentication via Clerk and payments via Stripe.
• You need secure data storage and querying via Supabase with Row-Level Security (RLS).
• You must support uploading financial spreadsheets, parsing and normalizing data, and running anomaly detection.
• You want executive reports with export-ready data dashboards and periodic summaries.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude Code, an AI software engineer responsible for delivering a complete AI Finance Analyst SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe. Your output must be pasteable into CLAUDE.md.

Architecture rules
- Use Next.js App Router with TypeScript and server components where possible.
- Build a multi-tenant architecture with per-tenant data isolation via Supabase Row-Level Security (RLS).
- All API endpoints must live under /src/app/api and validate Clerk sessions.
- Prefer service-layer logic in /src/services and keep UI in /src/app/finance.
- Use Stripe webhooks for payments and event handling; verify signatures server-side.

File structure rules
- /src/app/finance for UI routes (dashboard, reports, upload).
- /src/components for shared UI elements.
- /src/lib for shared utilities.
- /src/services for business logic (auth, database adapters, payments).
- /tests for unit/integration tests.

Authentication rules
- Clerk manages authentication and sessions.
- All sensitive endpoints require an authenticated Clerk session.
- Do not expose Clerk tokens to the client; use server-side guards.

Database rules
- Supabase Postgres with RLS enabled on all user-owned tables.
- Tables: accounts, transactions, uploads, anomalies, reports, users.
- Avoid over-fetching; only fetch data for the authenticated user or tenant.
- Encrypt sensitive fields at rest where the provider supports it and ensure TLS in transit.

Validation rules
- Validate all inputs against strict TypeScript types and runtime guards.
- Spreadsheet uploads must support CSV and Excel; validate schema and mandatory columns.
- All numeric data must be parsed to decimal with fixed precision; handle nulls safely.

Security rules
- Do not reveal API keys or secret tokens on the client.
- Validate Stripe webhook signatures; reject invalid events.
- Implement CSRF protection for state-changing actions; use HTTPS everywhere.
- Do not bypass authentication or authorization checks.

Testing rules
- Unit tests for services (auth, database adapters, data normalization).
- Integration tests for API routes and Supabase interactions using a mock or test database.
- End-to-end tests for onboarding, upload flow, and dashboard using Playwright.

Deployment rules
- Deploy to Vercel with environment variables for Next.js and Stripe/ Clerk config.
- Enable preview deployments for PRs; run automated tests on each push.
- Monitor dependencies for security advisories and update promptly.

Things Claude must not do
- Do not hardcode secrets in code blocks.
- Do not bypass Clerk authentication or leak user data.
- Do not implement client-side-only security checks; enforce server-side guards.
- Do not create API surfaces that bypass Supabase RLS or Stripe webhook validation.

Recommended Project Structure

root/
├─ package.json
├─ tsconfig.json
├─ next.config.js
├─ .env.example
├─ src/
│  ├─ app/
│  │  ├─ finance/
│  │  │  ├─ dashboard/
│  │  │  ├─ reports/
│  │  │  └─ upload/
│  │  └─ api/
│  │     ├─ auth/
│  │     └─ payments/
│  ├─ components/
│  ├─ lib/
│  │  └─ analytics/
│  ├─ services/
│  │  ├─ auth.ts
│  │  ├─ supabase.ts
│  │  └─ stripe.ts
│  └─ styles/

Core Engineering Principles

• Clear separation of concerns between UI, business logic, and data access.
• End-to-end type safety with TypeScript and runtime validations.
• Security by default: enforce Clerk authentication, Supabase RLS, and Stripe webhook verification.
• Scalability: server components, edge rendering for dashboards, and asynchronous data processing for uploads and analytics.
• Observability: structured logs, metrics, and tracing for critical paths like auth, payments, and data processing.

Code Construction Rules

• Define TypeScript interfaces for all data shapes (FinanceAccount, Transaction, UploadRecord, Anomaly, Report).
• All API routes must verify Clerk session and enforce per-user/tenant access controls.
• Spreadsheet parsing must support CSV and Excel; require explicit column mappings to the finance schema.
• Encapsulate business logic in /src/services; keep Next.js pages light and present data via props or API calls.
• Stripe interactions must be centralized in a payments service with webhook validation.
• Store sensitive metadata in Supabase with restricted access; lean on RLS for authorization.

Security and Production Rules

• Enable Supabase RLS with tenant-scoped policies; test with realistic tenant data.
• Validate Stripe webhook signatures and keep webhook endpoints strictly behind Clerk-authenticated routes when appropriate.
• Use environment-based feature flags; avoid enabling experimental features in production.
• Implement CSRF protection for state-changing endpoints and enforce TLS/HTTPS.
• Avoid logging sensitive data; redact personal and financial information in logs.

Testing Checklist

• Unit tests for services (auth, data adapters, parsing logic).
• Integration tests for Supabase queries, RLS policies, and Clerk auth flows.
• End-to-end tests for onboarding, upload flow, dashboards, and reports using Playwright.
• Validation tests for spreadsheet parsing with edge cases (missing columns, invalid data types).

Common Mistakes to Avoid

• Relying on client-side validation for security-critical paths.
• Neglecting Supabase RLS and tenant data isolation in multi-tenant scenarios.
• Storing secrets in code blocks or public repository files.
• Skipping validation of uploaded spreadsheets leading to data quality issues.

Related implementation resources: AI Use Case for Independent Publishers Using Amazon Sales Data To Analyze Which Book Genres Are Experiencing Growth and Skill Files for PMs: Building Realistic Clickable SaaS Demos with CLAUDE.md Templates.

FAQ

• What is this CLAUDE.md Template for? It provides a copyable CLAUDE.md template to build a production AI Finance Analyst SaaS stack with Next.js, TS, Supabase, Clerk, and Stripe, including spreadsheet uploads, anomaly detection, and executive reports.
• Which stack does this template target? Next.js with TypeScript, Supabase for data, Clerk for authentication, Stripe for payments, plus spreadsheet processing and anomaly-detection modules.
• How do I start using the template? Copy the CLAUDE.md block, adapt paths to your project structure, and run the tests and deployment steps described in the template.
• How is data secured in this template? Data resides in Supabase with Row-Level Security; authentication is via Clerk; Stripe webhooks are validated; secrets live in environment variables.
• How are spreadsheets processed? Uploads are parsed (CSV/Excel), validated against the finance schema, normalized, and stored in Supabase for analytics and anomaly detection.