CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe for Customer Feedback Analytics SaaS

Overview

The CLAUDE.md template describes how to build a complete Customer Feedback Analytics SaaS stack using Next.js, TypeScript, Supabase, Clerk, Stripe, and Claude Code. It provides concrete constraints, architecture rules, and a copyable CLAUDE.md block that engineers can paste into their repository to standardize setup, security, testing, and deployment.

Direct answer: This page delivers a ready-to-paste CLAUDE.md template that codifies the stack decisions, data models, and production rules for a sentiment-analysis powered analytics SaaS with theming and executive summaries.

When to Use This CLAUDE.md Template

• Starting a new Customer Feedback Analytics SaaS project with the described stack (Next.js, TS, Supabase, Clerk, Stripe).
• Standardizing architecture, security, and deployment rules across a team.
• Documenting the expected data flows for sentiment analysis, themes extraction, and executive summaries.
• Providing a copyable CLAUDE.md block for onboarding Claude Code to the project.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are a Senior Full Stack Engineer responsible for delivering a production-ready Customer Feedback Analytics SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe. You will implement sentiment analysis, themes, executive summaries, dashboards, and data pipelines. Be precise about constraints and avoid unneeded abstractions.

Architecture Rules:
- Use Next.js 14+ with App Router and TypeScript.
- Adopt a clean architecture: domain/services/repositories, API routes, and UI components.
- Primary techs: Supabase for database/auth, Clerk for authentication, Stripe for billing.
- Data model focuses on: customers, feedbacks, sentiments, themes, summaries, metrics.
- All server-side logic must run in server components or edge functions when possible.
- All secrets must be retrieved from environment variables at build/run time; never inline secrets in code or CLAUDE prompts.
- Use SSR where appropriate for SEO and initial data hydration; hydrate with client components where interactions are needed.
- Implement secure webhooks for Stripe and Clerk events; verify signatures.

File Structure Rules:
- Maintain a clear monorepo layout: apps/web, apps/api, packages/, infra/, domain/
- Do not include unrelated tech stacks or tools.
- Place domain models in domain/models/ and services in domain/services/.
- Place all API handlers under apps/web/app/api/.
- Put infrastructure adapters in infra/ (db adapters, billing adapters, etc.).

Authentication Rules:
- Clerk handles all user authentication and session management.
- Protect API routes with Clerk middleware or server-only checks.
- Enforce role-based access: admin, analyst, viewer.

Database Rules:
- Supabase Postgres with RLS enabled.
- Create policies for reading feedbacks by user/customer and writing new feedback entries only as allowed.
- Normalize schema: customers, feedbacks (content, sentiment, createdAt), themes, summaries, metrics.

Validation Rules:
- Validate all inputs on the server side; enforce TS types and runtime checks.
- Sanitize text inputs to prevent injection and XSS in UI displays.

Security Rules:
- Do not expose secret keys to the client.
- Use environment variables for API keys; implement server-only access.
- Enforce CSRF protection for state-changing operations via Clerk security features.
- Validate Stripe webhook signatures; never trust client-sent webhook data.

Testing Rules:
- Unit tests for domain logic (sentiment analysis, theme extraction).
- Integration tests for API routes (feedback submission, user onboarding, billing events).
- End-to-end tests for critical flows (feedback capture, sentiment, themes, executive summaries generation).

Deployment Rules:
- Deploy on a platform supporting Next.js deployment (e.g., Vercel) with proper ENV vars for Supabase, Clerk, Stripe.
- Use automated previews for PRs; ensure static optimization where possible.
- Enable monitoring and error tracking; collect usage metrics for dashboards.

Do Not:
- Do not hard-code secrets in code or CLAUDE.md.
- Do not bypass authentication or expose admin routes to non-admin roles.
- Do not introduce client-side secrets or server-side constraints that degrade security.

Recommended Project Structure

apps/web/                  # Next.js frontend app
  app/                     # App Router structure
  components/
  hooks/
  styles/
  app/
  page.tsx
  layout.tsx
  ...
apps/api/                  # API surface (optional microservices)
  src/
  handlers/
domain/
  models/
  services/
  repositories/
infra/
  db/
  billing/
  messaging/
packages/
  core/
  analytics/

Core Engineering Principles

• Type safety and explicit contracts across domains.
• Single source of truth for feedback data with clear data ownership.
• Security-first by default: no secrets on the client, strict access control.
• Incremental delivery with measurable outcomes (metrics-first design).
• Observability: structured logging, tracing, and error reporting.

Code Construction Rules

• Prefer Server Components for data fetching and UI composition where possible.
• Use TypeScript types for all API payloads; share types between client and server via a shared library.
• Store sensitive data only in secure environment variables; never in source code.
• Structure code to minimize bundle size; lazy-load heavy features (sentiment analysis, themes processing).
• Keep CLAUDE.md blocks self-contained with all rules and do-not-steps clearly listed.

Security and Production Rules

• Enable Supabase Row-Level Security and write policies that sandbox user data properly.
• Validate and verify Stripe webhooks with signatures on the server.
• Use Clerk middleware to guard API routes and pages; enforce role checks.
• Regularly rotate secrets and monitor for anomalous activity.

Testing Checklist

• Unit tests for sentiment scoring and theme extraction logic.
• API integration tests for feedback submission, user auth, and billing events.
• End-to-end tests for end-user workflows: signup, submit feedback, view analytics, generate executive summaries.
• Security tests for input validation, RBAC, and webhook handling.
• Performance checks for sentiment analysis pipeline under load.

Common Mistakes to Avoid

• Not enabling RLS in Supabase or misconfiguring policies to expose data.
• Embedding secrets in CLAUDE.md or client code.
• Assuming client-side can perform secure billing operations.
• Over-optimizing early without proper telemetry and observability.

Related implementation resources: AI Use Case for Outlook Inbox and Customer Sentiment Analysis and CLAUDE.md as Project Memory: Practical AI Development Workflows and Templates.

FAQ

What is this CLAUDE.md Template used for?

It provides a ready-to-use CLAUDE.md block to standardize a Next.js + TS + Supabase + Clerk + Stripe Customer Feedback Analytics SaaS, including sentiment analysis and thematic summaries.

Which stack does this template cover?

Next.js, TypeScript, Supabase, Clerk, Stripe, sentiment analysis, themes, and executive summaries, all wired for Claude Code.

How do I apply the CLAUDE.md template block?

Copy the block under Copyable CLAUDE.md Template and paste it into your repository as the canonical CLAUDE.md for the project.

How are authentication and billing handled?

Clerk manages authentication; Stripe handles billing. Webhooks and server-side checks ensure secure processing.

What are the deployment considerations?

Deploy to a platform like Vercel with environment variables for Supabase, Clerk, and Stripe, and enable monitoring and alerts.

Where can I customize data models?

In domain/models and infra/db with Supabase policies; ensure alignment with your CLAUDE.md rules.