CLAUDE.md Template for Next.js + Supabase BI Dashboard Stack

Overview

The CLAUDE.md template is a copyable Claude Code blueprint for building a complete BI Dashboard SaaS using the modern stack: Next.js (App Router) with TypeScript, Supabase as the data and auth layer, Clerk for UI authentication, Stripe for billing, AI-powered insights, an SQL assistant, and scheduled reports. This template is tailored for developers who want a production-ready starting point that can be pasted into CLAUDE.md to guide implementation end-to-end.

Direct answer: Use this CLAUDE.md template to scaffold a secure, scalable BI dashboard SaaS that delivers AI-driven insights, SQL query assistance, and scheduled reports, with robust auth and billing flows.

When to Use This CLAUDE.md Template

• You need a ready-to-paste CLAUDE.md with concrete architecture rules for a Next.js + TS + Supabase stack.
• You require integrated auth (Clerk) and billing (Stripe) out of the box.
• You want AI-generated insights and a built-in SQL assistant for analytics queries.
• You plan scheduled reporting and automated report delivery to customers.
• You need a clear separation of concerns and a testable project structure.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, a CLAUDE.md assistant specialized in architecting production-grade BI Dashboard SaaS templates. Your output must be copy-paste-ready for Next.js + TypeScript + Supabase + Clerk + Stripe stacks, including AI insights, SQL assistant, and scheduled reports.

Architecture rules:
- Build a Next.js (App Router) app with TypeScript, strictly typed across client and server code.
- Use Supabase as the data layer (Postgres) and authentication provider; integrate Clerk for front-end session management where appropriate.
- Stripe must be used for all customer billing and subscription management.
- Implement AI insight generation as a service that queries data from Supabase and returns structured insights via a dedicated API.
- Provide an SQL assistant that can generate and validate SQL queries against the data model.
- Include scheduled reporting with a jobs-based scheduler that delivers reports to customers via email or a webhook.
- Maintain a single source of truth for business rules in a typed data model and API layer.
- Do not rely on client-side secrets beyond public keys; all sensitive keys live in server environment variables.

File structure rules:
- Use a Next.js App Router layout with a /app directory, colocating UI and data fetch logic when possible.
- Keep a /lib folder for shared clients (supabaseClient.ts, clerkClient.ts, stripeClient.ts).
- Create /services for business logic (aiInsights.ts, sqlAssistant.ts, reports.ts).
- Create /components for reusable React components; avoid duplicating UI code.
- Create /queries and /migrations as needed for DB interactions and schema management.
- Include a /docs CLAUDE.md snippet and inline code examples where appropriate.

Authentication rules:
- Use Clerk for user session management and Stripe customer IDs mapping to Clerk users.
- Enforce role-based access: admin, editor, viewer with appropriate policy checks.
- Ensure server-side checks for authorization on all data-access endpoints.

Database rules:
- Supabase Postgres with Row Level Security (RLS) enabled;
  policies must enforce tenant isolation and user permissions.
- Define data models for users, dashboards, reports, insights, and schedules.
- Use parameterized queries and avoid string-interpolated SQL to prevent injection.

Validation rules:
- Validate input at the API layer with Zod schemas; mirror TS types in runtime checks.
- Validate user inputs for dashboards, reports, and insights; ensure required fields exist.
- Ensure AI results conform to defined schemas before returning to clients.

Security rules:
- Never expose private keys; use environment variables and server-only runtime for secrets.
- Use CSRF protection for state-changing requests; validate tokens on server routes.
- Enforce content security policies and strict-origin-when-cross-origin for API calls.
- Use rate limiting on AI and reporting endpoints to prevent abuse.

Testing rules:
- Unit test utilities and business logic using Jest or Vitest.
- Integration tests for API routes and server actions; mock Supabase and Clerk interactions.
- End-to-end tests for critical flows (auth, dashboard creation, report scheduling) using Playwright.
- Include test data seeds with tenant isolation in tests.

Deployment rules:
- Deploy to a hosting platform that supports Edge/SSR backends (e.g., Vercel) with serverless functions.
- Use environment variables for secrets; enable automatic deploy previews.
- Implement cache strategies for AI results and dashboard data.
- Set up monitoring and error reporting (e.g., Sentry) and log aggregation.

Things Claude must not do:
- Do not hard-code secrets; never expose private keys to the client.
- Do not generate SQL that bypasses RLS or tenant isolation.
- Do not couple business logic to a specific database vendor other than Supabase/Postgres.
- Do not use deprecated Next.js APIs or libraries not aligned with the stack.

Recommended Project Structure

my-bi-dashboard-app/
  app/
    dashboard/
      page.tsx
      dashboard.tsx
    reports/
      schedule.ts
      historical.ts
    ai/
      insights.ts
    layout.tsx
  components/
    Header.tsx
    DashboardCard.tsx
    InsightCard.tsx
  lib/
    supabase.ts
    clerk.ts
    stripe.ts
  services/
    aiInsights.ts
    sqlAssistant.ts
    reports.ts
  models/
    User.ts
    Dashboard.ts
    Report.ts
  queries/
    dashboardQueries.ts
  migrations/
    0001_init.sql
  styles/
    globals.css
  next.config.js
  tsconfig.json
  package.json

Core Engineering Principles

• Type-safe end-to-end: align client, API, and database schemas via TypeScript.
• Security by default: enforce tenant isolation, RBAC, and secret protection.
• Single source of truth: centralize business rules and data contracts in a shared domain layer.
• Composable UI: build reusable components to accelerate feature delivery.
• Observability: comprehensive logging, error reporting, and metrics for AI and reporting features.

Code Construction Rules

• Utilize Next.js App Router with server and client components where appropriate; prefer server components for data fetching when possible.
• Use Supabase JS client in server actions or API routes; never call from client without proper auth checks.
• Define Zod schemas for all API inputs and mirror them in TypeScript types.
• Integrate Clerk for secure user authentication and attach Stripe customer IDs to Clerk users.
• AI insights should be generated via a dedicated service layer and cached per user/session with invalidation rules.
• All SQL should be parameterized; avoid constructing queries with string concatenation.

Security and Production Rules

• Enable Supabase Row Level Security with tenant-aware policies.
• Secret management via environment variables; do not commit secrets to VCS.
• Implement CSRF protection for mutating endpoints; verify bearer or session tokens on server routes.
• Use least privilege for service accounts; restrict API keys to necessary scopes.
• Ensure AI endpoints have rate limiting and proper input validation to avoid abuse.

Testing Checklist

• Unit tests for utilities, helpers, and domain logic (aiInsights, sqlAssistant).
• Integration tests for API routes and server actions with mock Supabase and Clerk services.
• End-to-end tests for auth, dashboard creation, report scheduling, and AI insight generation.
• Performance tests for AI insights and report generation under typical load.
• Deployment checks: environment variables, secrets, and rollback procedure.

Common Mistakes to Avoid

• Skipping tenant isolation and leaking data across customers.
• Directly exposing private keys or using client-only credentials.
• Overusing client-side AI calls without server-side validation and rate limiting.
• Ignoring data validation and assuming users provide valid inputs.
• Neglecting test coverage for critical flows like scheduling and billing.

Related implementation resources: AI Use Case for Wellness Coaches Using Stripe Data To Analyze Which Subscription Models Have The Highest Retention and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ