CLAUDE.md Template: Sales Analytics SaaS with Next.js, TS, Supabase, Clerk, Stripe

Overview

The CLAUDE.md template is a copyable Claude Code instruction block designed to guide Claude Code in delivering a production-ready Sales Analytics SaaS stack built with Next.js, TypeScript, Supabase (PostgreSQL), Clerk for authentication, Stripe for billing, plus AI forecasting, pipeline analysis, and rep performance dashboards. This page provides a complete, paste-ready CLAUDE.md block tailored to this stack and a stack-specific project structure to start fast.

Direct answer for developers: paste the CLAUDE.md block below into your CLAUDE.md file to generate a full-stack blueprint, including architecture rules, data models, validation, security, tests, and deployment considerations for this Stack.

When to Use This CLAUDE.md Template

• Kick off a production-ready Sales Analytics SaaS using Next.js + TS with a Supabase/Postgres backend.
• Incorporate Clerk for authentication and Stripe for billing with secure payment flows.
• Integrate AI forecasting for sales trends and pipeline analytics alongside rep performance dashboards.
• Predefine architecture, validation, security, tests, and deployment constraints to prevent drift.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a Senior Full-Stack Architect and Claude Code specialist tasked with delivering a complete Sales Analytics SaaS stack using Next.js (App Router), TypeScript, Supabase, Clerk, Stripe, AI forecasting, pipeline analysis, and rep dashboards. Produce production-ready code, schemas, and deployment guidance. Do not assume Prisma; use Supabase Postgres and Clerk for auth. Do not bypass server-side validation or expose secrets on the client.

Architecture rules:
- End-to-end, production-grade architecture with a clean separation of concerns: frontend, API routes, and database access via a single service layer.
- Use Next.js App Router with TS, React 18, TailwindCSS; strictly avoid framework drift.
- Supabase as the primary database andauth provider; Clerk for user authentication and session management; Stripe for billing.
- Implement serverless API routes for business logic (forecasting, pipeline analytics, dashboards) with strict input validation.
- All secrets must live in environment variables; never embed in frontend code.
- Implement observability hooks (logs, metrics) and structured error handling.

File structure rules:
- Keep a flat, predictable layout for frontend components and a separate services layer for API calls.
- Use a single src/ or app/ root with clear module boundaries.
- Include a dedicated db/ directory for migrations and seed data; a services/ directory for clients and business logic; a features/ directory for domain-specific code (forecast, pipeline, dashboards).

Authentication rules:
- Clerk must guard all protected pages.
- Use server components where possible; protect API routes with Clerk authentication checks.
- Do not rely on client-side checks for authorization.

Database rules:
- Supabase Postgres with tables: users (managed by Clerk), customers (subscription data), pipelines, forecasts, reps, dashboards, events.
- All foreign keys use cascade-safe relations; indexes on frequently queried fields (tenant_id, user_id, date).
- Use RLS (Row Level Security) with policies based on tenant ownership and Clerk user_id.

Validation rules:
- Validate inputs with Zod on all API routes.
- Validate schema shapes for forecast, pipeline, and dashboard data before DB writes.
- Normalize dates and numeric fields; enforce non-null constraints.

Security rules:
- Do not embed secrets in client code; use .env and runtime config。
- Validate webhook signatures for Stripe and any external integrations.
- Enforce CSRF protection for state-changing endpoints where applicable.

Testing rules:
- Unit tests for services and validators; integration tests for API routes against a test database.
- E2E tests for authentication, dashboard rendering, and critical flows using Playwright or Cypress.
- CI should run type checks, lint, tests, and build verification.

Deployment rules:
- Target Vercel or similar hosting with automatic deployments on push to main; configure environment variables for Supabase, Clerk, and Stripe.
- Set up Stripe webhooks, database migrations, and backup strategies.
- Use edge caching for dashboards where applicable and enable server-side rendering for data-intensive pages.

Things Claude must not do:
- Do not generate client-only DB credentials or embed secret keys in frontend code.
- Do not use Prisma or any ORM not compatible with Supabase; use Supabase client instead.
- Do not bypass server-side authentication checks or expose protected APIs.
- Do not hardcode production API keys or route handlers that skip validation.

---
// Recommended steps to instantiate the project from this CLAUDE.md
- Create Next.js app with app directory and TS config.
- Initialize Supabase client and Clerk provider; wire Stripe checkout session.
- Implement domain services: ForecastService, PipelineService, DashboardService.
- Create database schema for pipelines, forecasts, reps, dashboards; enable RLS.
- Build UI for analytics dashboards with charts, filters, and export options.
- Add tests, CI, and deployment configurations.

Recommended Project Structure

apps/                  # Monorepo apps (frontend + infra)
  web/                   # Next.js frontend (App Router)
    app/
      layout.tsx
      page.tsx
      dashboards/
        page.tsx
    components/
    hooks/
    lib/
      supabaseClient.ts
      clerkClient.ts
      stripeClient.ts
    styles/
    public/
  api/                   # Serverless API (optional if colocated)
    forecasting/
      route.ts
    pipelines/
      route.ts
db/
  migrations/
  seed.ts
  schema.sql
packages/                # Optional additional packages or libs
  shared/                # Shared types and utilities
    types.ts
    validators.ts
.env                    # Environment variables (not checked in)
.env.local

Core Engineering Principles

• Single source of truth: canonical data models for pipelines, forecasts, and dashboards.
• Strong typing: TypeScript everywhere; validated inputs with Zod.
• Security by default: server-side auth checks, strict RBAC, and proper secret management.
• Clear separation of concerns: UI, business logic, and data access layers are decoupled.
• Observability: structured logging, metrics, and traceability for critical workflows.

Code Construction Rules

• Use Next.js App Router with TS and server components where appropriate.
• Supabase as DB: use @supabase/supabase-js for client-side DB calls; avoid direct SQL from the client.
• Clerk for authentication: wrap pages with withAuth and use ClerkProvider on the app root.
• Stripe for billing: implement checkout sessions server-side; validate webhooks securely.
• AI forecasting: modular services that consume sanitized input and write forecasts to DB with proper provenance.
• Validation: enforce schema validation with Zod on all data paths.
• Security: never hardcode secrets; use environment variables; enable CSRF where needed.
• Testing: unit tests for services, integration for APIs, and end-to-end tests for dashboards.
• Performance: lean API routes; paginate large datasets; cache infrequently changing dashboards.

Security and Production Rules

• Enable Row Level Security on all critical tables in Supabase; define tenant-based policies.
• Validate Stripe webhook signatures and store only necessary data in DB.
• Serve data-heavy dashboards with server-side rendering or edge caching to reduce latency.
• Enforce content security policy (CSP) and strict transport security (HSTS) in production.

Testing Checklist

• Unit tests for validators, services, and utilities.
• Integration tests for API routes with a test database (seeded data).
• End-to-end tests for authentication flow and dashboard rendering.
• Deployment validation: migrations run, secrets loaded, webhook endpoints reachable.

Common Mistakes to Avoid

• Hardcoding secrets or API keys in frontend code or CLAUDE.md templates.
• Assuming Prisma is compatible with Supabase; use the Supabase client instead.
• Skipping server-side authentication checks or RBAC for sensitive endpoints.
• Ignoring proper validation and error handling leading to runtime crashes.

Related implementation resources: AI Use Case for Outlook Inbox and Customer Sentiment Analysis and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ

What stack does this CLAUDE.md Template cover?

Next.js with TypeScript, Supabase Postgres, Clerk for authentication, Stripe for billing, plus AI forecasting, pipeline analysis, and rep dashboards.

How do I use this CLAUDE.md Template?

Copy the content of the copyable CLAUDE.md block into your CLAUDE.md file and follow the project structure and rules to generate the full stack.

What is the recommended project structure?

A Next.js frontend in apps/web with a server/api layer, a db/ directory for migrations, and a shared/lib/services for business logic.

Which services are used for auth and billing?

Clerk handles authentication; Stripe handles billing; all webhooks are validated securely.

How is security enforced in production?

Server-side validation, RBAC/RLS on the database, secret management via environment variables, and hardened API routes.