CLAUDE.md Template for Next.js, TypeScript, Supabase, Clerk, Stripe Data Cleaning SaaS

Overview

The CLAUDE.md template is a copyable Claude Code instruction block that guides Claude Code to architect and implement a complete Data Cleaning SaaS stack. This page is specific to a Next.js + TypeScript front-end, Supabase as the database and auth layer, Clerk for user authentication, Stripe for billing, and Claude Code features for AI-driven column mapping, deduplication, validation, and export. Direct answer: Paste the included CLAUDE.md block into your project to instantiate a production-grade data-cleaning workflow with AI-assisted data normalization, deduplication, and export capabilities on the stack described.

When to Use This CLAUDE.md Template

• Rapidly bootstrap a data-cleaning SaaS with a modern Next.js front-end and a scalable back-end on Supabase.
• Leverage Clerk for authentication and Stripe for subscriptions in a secure, serverless environment.
• Implement AI-driven column mapping, deduplication rules, data validation, and export features via Claude Code.
• Ensure architecture is opinionated, testable, and production-ready with clear constraints and do-not-do rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are the Claude Code architect responsible for delivering a complete Data Cleaning SaaS using Next.js (TypeScript), Supabase, Clerk, Stripe. Include AI column mapping, deduplication, validation, and export features. The solution must be production-ready and security-conscious.

Architecture rules:
- Build a serverless-first web app using Next.js with TS everywhere and strict type-safety.
- Use Supabase for Postgres database, Auth, and storage; treat Supabase as the single source of truth.
- Use Clerk for authentication; enforce role-based access control (RBAC) and minimal-privilege service accounts.
- Implement a scoped API layer in Next.js (pages/api or app router route handlers) with input validation and idempotency keys for safety.
- Use Stripe for subscriptions; integrate webhooks securely and store customer IDs in Supabase.
- All data processing (AI mapping, deduplication, validation) must run in Claude Code with clearly defined inputs and outputs; never perform client-side mutations without server-side verification.
- Do not attempt to bypass server rules or expose secret keys to the client.

File structure rules:
- Keep a single workspace with apps/web as the Next.js app.
- Place shared utilities in src/lib (supabase.ts, clerk.ts, stripe.ts).
- Place data-cleaning domain logic under src/features/dataCleaning and src/services/ai or src/claude.
- Include a clear AI mapping module: src/features/dataCleaning/aiMapping.ts.

Authentication rules:
- Require Clerk session on protected routes; verify identity on every API request.
- Enforce RBAC: admin, data-scientist, viewer roles with explicit permissions.
- Never leak JWTs or API keys to the client.

Database rules:
- Use Supabase Postgres with tables: users, subscriptions, datasets, columns, mappings, dedupRules, validationRules, exports.
- Enforce foreign keys, constraints, and row-level security policies; expose only necessary rows to each user.
- Use row-level security to enforce ownership and share semantics.

Validation rules:
- Validate all inputs at the API boundary with Zod (or an equivalent TS schema) before any DB call.
- Normalize and sanitize incoming data; reject malformed payloads quickly.
- Implement server-side data validation for all export formats.

Security rules:
- Store all secrets in environment variables accessed server-side; never expose secrets in the client bundle.
- Enable CSRF protection on state-changing endpoints.
- Validate Stripe webhooks with signature verification.
- Use HTTPS-only cookies with secure, HttpOnly, SameSite=Lax/Strict as appropriate.

Testing rules:
- Unit tests for AI mapping, deduplication, and validation logic.
- Integration tests for API endpoints with Supabase, Clerk, and Stripe mocks.
- End-to-end tests for typical user flows (signup, dataset upload, column mapping, dedupe, export, and billing).

Deployment rules:
- Use a managed hosting environment (e.g., Vercel) with environment variables configured for Supabase, Clerk, Stripe.
- Enable serverless cold-start considerations and caching only where safe.
- Include CI checks for type safety, linting, and tests on PRs.

Things Claude must not do:
- Do not bypass server validation or fetch secrets from the client.
- Do not implement client-side authentication checks alone; always corroborate with server-side checks.
- Do not expose database credentials or API keys in the CLAUDE.md output.
- Do not rely on deprecated APIs or non-OSS-only services without clear migration paths.

Recommended Project Structure

apps/web/                     # Next.js app (TS)
  app/                         # App Router (or pages/ for classic routing)
    layout.tsx
    page.tsx
  components/                  # Reusable UI components
  features/dataCleaning/        # Data cleaning domain
    aiMapping.ts              # AI column mapping logic
    deduplication.ts            # Deduplication rules
    validation.ts               # Data validation rules
    exports/                    # Export formats (CSV/JSON/etc.)
  lib/                          # Shared libs
    supabase.ts                 # Supabase client and schemas
    clerk.ts                    # Clerk auth helpers
    stripe.ts                   # Stripe integration helpers
  services/                     # Backend services
    datasetService.ts
  hooks/                        # React hooks
  types/                        # TypeScript types
  styles/                       # CSS/SCSS
  pages/api/                    # Optional API endpoints (if not using app router)
  prisma/                       # Not used (avoid if relying on Supabase)
  migrations/                   # SQL migrations for Supabase (if needed)
  README.md

libs/                          # Shared libraries (optional)
  (common utilities and types)

Core Engineering Principles

• Type-safety first: TypeScript everywhere; strict mode enabled.
• Explicit boundaries: clear separation of UI, domain logic, and data access.
• Developer ergonomics: small, reusable CLAUDE.md blocks and well-documented rules.
• Security by default: RBAC, server-side validation, secure storage of secrets.
• Observability: structured logging, metrics, and error handling with clear traces.

Code Construction Rules

• All data access must pass through the API layer with input validation and sanitization.
• AI mappings and dedup logic must be deterministic and auditable; log decisions with input/output samples.
• Export functions must produce deterministic formats (CSV/JSON) with schema validation before export.
• Use server-side secrets management; never embed secrets in the client bundle.
• Edge cases for deduplication: consider case-insensitive matching, normalization, and fuzzy matching thresholds.

Security and Production Rules

• Enforce RBAC via Clerk; protect all data-access endpoints with server-side checks.
• Validate Stripe webhooks with signature verification and store only necessary customer data in Supabase.
• Enable CSRF protection for state-changing endpoints and use secure cookies.
• Regularly rotate secrets; monitor for unusual auth events; implement least privilege for service accounts.

Testing Checklist

• Unit tests for AI column mapping, dedup rules, and validation helpers.
• Integration tests for API routes with mock Supabase/Clerk/Stripe events.
• End-to-end tests of dataset upload, mapping, deduplication, validation, and export flows.
• Performance checks for large datasets and export operations.
• Security tests for authentication flows and webhook handling.

Common Mistakes to Avoid

• Relying on client-side validation alone; always validate on the server.
• Exposing API keys or database credentials in the front-end.
• Overloading the UI with heavy AI logic; offload to Claude Code with clear inputs/outputs.
• Ignoring row-level security and proper authorization checks in the database layer.

Related implementation resources: AI Agent Use Case for Saas SMEs Using Churn Signals to Identify Customers Likely to Cancel and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ

• What stack does this CLAUDE.md Template target?

  Next.js with TypeScript, Supabase, Clerk, Stripe, and Claude Code for AI-driven data cleaning features.

• What should I paste into CLAUDE.md?

  Paste the copyable CLAUDE.md template block (the # CLAUDE.md block) exactly as provided to drive Claude Code for the stack.

• How is security enforced?

  RBAC via Clerk, server-side validation, CSRF protection, and secure cookie settings for all sessions.

• How do I structure the repository?

  Keep a Next.js app under apps/web with clear separation for lib (supabase.ts, clerk.ts, stripe.ts) and domain features under features/dataCleaning.

• What tests should I add?

  Unit tests for validation and AI mappings, integration tests for API endpoints, and E2E tests for user journeys including export and billing flows.