CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe AI Spreadsheet Analytics SaaS

Overview

The CLAUDE.md template is a copyable Claude Code blueprint for a complete AI Spreadsheet Analytics SaaS built with Next.js, TypeScript, Supabase, Clerk, Stripe, file upload, chart generation, and natural language queries. This CLAUDE.md Template page includes a ready-to-paste instruction block and a stack-specific project layout you can reuse to bootstrap production-grade apps.

Direct answer: This template encodes a concrete, executable Claude Code guide that you can paste into CLAUDE.md to generate consistent architecture, file layout, and rules for the stack described above.

When to Use This CLAUDE.md Template

• When you are building an AI-driven Spreadsheet Analytics SaaS with Next.js and TypeScript.
• When you rely on Supabase for database, storage, and auth, complemented by Clerk for user management.
• When you need Stripe-based payments and file uploads integrated in the flow.
• When you want NLQ (natural language queries) supported by Claude Code to query data and generate charts on demand.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, an automation assistant who writes precise, executable Claude Code for a Next.js + TypeScript + Supabase + Clerk + Stripe AI Spreadsheet Analytics SaaS. Your outputs are copy-paste ready and strictly conform to this template.

Architecture rules:
- Build with Next.js App Router, TypeScript, and server components where appropriate.
- Use Supabase for authentication, database, and storage. Use Clerk for user management and session handling.
- Integrate Stripe for payments, subscriptions, and webhooks. Do not bypass Stripe; implement webhooks securely.
- Implement NLQ via Claude Code to translate natural language queries into SQL or data visualizations on the frontend, backed by Supabase functions where possible.
- Ensure a clean separation between UI, business logic, and data access layers.
- All secrets must live in environment variables and accessed server-side. No secrets on the client.

File structure rules:
- The repository must present a single source of truth for data access in a /db or /lib/db module.
- Use a feature-based structure inside app/ (e.g., app/spreadsheets/, app/dashboards/).
- Place Claude Code instruction blocks in CLAUDE.md at the project root so they can be reused by automation.

Authentication rules:
- Use Clerk for session mgmt and user profile, backed by Supabase consented auth flow.
- Protect pages using middleware to require authentication; only allow authorized roles.

Database rules:
- Use Supabase Postgres schema layout with tables: users, accounts, spreadsheets, queries, charts, uploads, payments.
- Enforce RLS policies to restrict data by user_id and tenant_id.
- Validate data types strictly; consider composite primary keys where needed.

Validation rules:
- Validate all inputs server-side; sanitize all user-provided values; enforce JSON schema where applicable.
- Validate file uploads (size, type) before storage; check for duplicates.

Security rules:
- Do not expose API keys or secrets in client code.
- Use signed URLs for uploads and downloads when possible.
- Enable CSRF protection on state-changing endpoints; log and monitor anomalous access.

Testing rules:
- Unit test pure functions in /lib and /utils.
- Integration tests for API routes and database access; mocking allowed for sensitive paths.
- End-to-end tests for signup, login, data upload, NLQ, and chart rendering.

Deployment rules:
- Deploy to a provider supporting Next.js App Router (Vercel, Netlify, etc.).
- Use environment variables for keys; set up Stripe webhooks in production.
- Enable proper caching and re-validation strategies; monitor with logs.

Things Claude must not do:
- Do not generate code that directly accesses secrets on the client.
- Do not implement insecure file upload paths; always validate and store securely.
- Do not bypass Clerk for authentication.
- Do not perform destructive migrations in production without explicit confirmation.
- Do not output any code that leaks database credentials.

Recommended Project Structure

my-ai-saas/
  apps/
    web/
      app/
        layout.tsx
        page.tsx
      components/
        Chart.tsx
        DataTable.tsx
        UploadButton.tsx
      lib/
        api/
          supabase.ts
          nlq.ts
        auth/
          clerk.ts
        db/
          client.ts
        payments/
          stripe.ts
        chart/
          chartUtil.ts
        file/
          upload.ts
      services/
        stripe.ts
        file-storage.ts
      hooks/
        useSpreadsheet.ts
      styles/
    public/
  next.config.js
  tsconfig.json

Core Engineering Principles

• Clear separation of concerns: UI, data access, auth, and payments are isolated behind clean boundaries.
• Single source of truth: All business data flows through a defined data layer (db/lib).
• Security-first: enforce least privilege, server-side secret handling, and strict input validation.
• Observability: structured logging and error reporting in all critical paths.
• Testability: unit/integration tests accompany features; CI runs tests on PRs.
• Deterministic builds: deterministic dependencies and lock files, with reproducible builds.

Code Construction Rules

• Use Next.js App Router with TypeScript; prefer server components for data fetching.
• All API interactions with Supabase must go through a typed data access layer.
• Authenticate via Clerk and verify user identity on secure pages; respect user roles.
• Implement NLQ as a Claude Code module that translates natural language queries into SQL or charts against a Supabase database.
• Chart rendering should be client-side with a lightweight library; avoid server-side rendering for heavy charts.
• File uploads must go to Supabase Storage with signed URLs and size/type checks.
• Payments and subscriptions managed via Stripe; verify webhooks on the server.
• Do not hard-code credentials; use environment variables.

Security and Production Rules

• Enforce CSRF protection and signed cookies; authenticate on all state-changing endpoints.
• Use row-level security (RLS) in Supabase to restrict access per user/tenant.
• Never expose secrets in client bundles; fetch secrets server-side only.
• Audit logs for auth, payments, and data mutations.
• Implement rate limiting on API routes; monitor anomalies.

Testing Checklist

• Unit tests for /lib and /utils; mock external services.
• Integration tests for API routes interacting with Supabase and Clerk.
• End-to-end tests covering signup, login, data ingestion, NLQ, chart rendering.
• Performance tests for NLQ latency and chart rendering under load.
• Value of environment-specific tests for production-like configuration.

Common Mistakes to Avoid

• Skipping server-side validation and trusting client input.
• Exposing private keys in client bundles.
• Not configuring Supabase RLS for access control.
• Over-using server components for simple UI tasks, causing over-fetching.
• Ignoring Stripe webhooks verification in production.

Related implementation resources: AI Agent Use Case for Packaging Designers Using Box Drop-Test Telemetry To Design Shock-Absorbent Corrugated Structures and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ

• What is the CLAUDE.md Template for this stack? A copyable Claude Code blueprint that codifies architecture, file layout, and rules for a Next.js + TS + Supabase + Clerk + Stripe AI Spreadsheet Analytics SaaS.
• Can I customize the stack for other data workloads? Yes. Adapt the data models, auth rules, and NLQ mappings to your dataset while preserving the Claude Code structure.
• How is authentication handled? Clerk handles session management; Supabase provides the database and storage; server-side checks enforce authorization.
• How do NLQ and charts interact? NLQ requests are translated by Claude Code into SQL or API calls, returning chart-ready results to the client.
• What about deployment? Deploy to a platform supporting Next.js App Router; configure environment variables and Stripe webhooks; monitor logs.