CLAUDE.md Template: Next.js TypeScript Supabase Clerk Stripe Helpdesk SaaS

Overview

The CLAUDE.md template is a copyable Claude Code page designed for building a complete Helpdesk SaaS stack using Next.js, TypeScript, Supabase, Clerk, Stripe, AI ticket classification, SLA monitoring, and a customer portal. It provides a ready to paste CLAUDE.md instruction block and concrete rules to guide implementation and ensure production readiness.

Direct answer: This CLAUDE.md template delivers a self contained Claude Code block that defines roles, architecture constraints, and production rules for the specified stack, enabling rapid, consistent rollout.

When to Use This CLAUDE.md Template

• Starting a new Helpdesk SaaS project with Next.js and TypeScript backed by Supabase.
• Seeking a standard architecture skeleton that enforces Clerk auth and Stripe billing.
• Integrating AI ticket classification for triage and SLA monitoring within a customer portal.
• Needing a copyable Claude Code block you can paste into CLAUDE.md to accelerate setup.

Copyable CLAUDE.md Template

# CLAUDE.md
- Project role: Lead Software Engineer building a Helpdesk SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI ticket classification, SLA monitoring, and a customer portal
- Architecture rules:
  - Use Next.js App Router with TypeScript; SSR where beneficial; keep UI components pure
  - Use Supabase for database and auth with Row Level Security; use Postgres; ensure separate schemas for tenants
  - Integrate Clerk for authentication; use email/password and OAuth providers; require session tokens; guard API routes
  - Use Stripe for billing; integrate subscription management; webhooks for events; test with test keys
  - AI ticket classification: integrate a Claude Code component that tags incoming tickets using a small model; store predictions in database; logs vs privacy
- File structure rules:
  - apps/portal/src/pages or app routes
  - apps/portal/src/components
  - apps/portal/src/lib
  - apps/portal/public
  - apps/api or services for server logic
  - libs for shared types and utils
- Authentication rules:
  - Clerk is the auth provider; use getServerSession on server components; protect sensitive routes
- Database rules:
  - Supabase Postgres; tables tenants tickets messages customers logs; implement RLS policies; store audit
- Validation rules:
  - Use Zod for input validation; all API route inputs validated on server
- Security rules:
  - Do not embed secrets in client side; use environment variables; enforce CSRF tokens for state changing endpoints; enforce TLS
- Testing rules:
  - Unit tests for services; integration tests for API endpoints; end to end tests for critical flows
- Deployment rules:
  - Deploy to Vercel or similar; configure environment variables; enable preview deployments
- Things Claude must not do:
  - Do not bypass authentication; do not access or log private customer data; do not call production endpoints from test environment

Recommended Project Structure

.
├─ apps
│  ├─ portal
│  │  ├─ public
│  │  └─ src
│  │     ├─ app
│  │     ├─ components
│  │     ├─ lib
│  │     └─ styles
│  ├─ api
│  │  └─ src
│  │     ├─ tickets
│  │     └─ auth
│  └─ supabase
│     ├─ database
│     │  ├─ migrations
│     │  └─ schemas
│     └─ README.md
└─ scripts

Core Engineering Principles

• Explicit contracts and self documenting CLAUDE.md blocks
• Secure by default with proper access controls and least privilege
• Single source of truth for data models and API contracts
• Composable, testable components with clear boundaries
• Predictable deployment and observable system

Code Construction Rules

• Use TypeScript everywhere for type safety
• Server components handle data fetching; client components render UI
• Supabase used for database; enable RLS; manage roles via policies
• Clerk for authentication; enforce session checks on protected routes
• Stripe for subscriptions; handle webhooks securely
• AI classification results stored with tickets; log predictions for auditing

Security and Production Rules

• Hide secrets behind environment variables; never commit keys
• Use HTTPS; enforce TLS; validate inputs; rate limit API endpoints
• Audit logs for sensitive actions; restrict access per tenant
• Regularly rotate IAM credentials; monitor for unusual activity

Testing Checklist

• Unit tests for services and utilities
• Integration tests for API routes and database access
• End to end tests for ticket lifecycle in the portal
• Static type checks and linting in CI

Common Mistakes to Avoid

• Relying on client side validation for security critical logic
• Skipping RLS policies or tenant isolation
• Storing secrets in client accessible code
• Overcomplicating architecture beyond the needs of the templates

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Skill files for maintainable AI middleware.

FAQ

What is this CLAUDE.md Template for Next.js TypeScript Supabase Clerk Stripe Helpdesk SaaS?

It provides a copyable Claude Code block with explicit project role rules and production guidelines to scaffold a fully functional Helpdesk SaaS.

What stack components are included?

Next.js with TypeScript for the frontend, Supabase for backend, Clerk for authentication, Stripe for billing, and AI ticket classification for triage with SLA monitoring.

How does Claude enforce architecture and security?

The CLAUDE.md block specifies architecture rules, security policies, and deployment constraints that you paste into your project as a starting point.

Can I adapt the template for SLA monitoring and customer portals?

Yes. The template includes guidance on SLA metrics, alerts, and a customer portal integration pattern that aligns with subscriptions and tickets.

What tests and deployments are recommended?

Include unit and integration tests for services and API routes; use CI to run tests and deploy to a hosting platform with environment variables configured.