CLAUDE.md Template for Mental Wellness Coaching App (Next.js, TypeScript, Supabase, Clerk, Stripe) - Claude Code

Overview

The CLAUDE.md template is a copyable blueprint for building a complete Mental Wellness Coaching App using Next.js TypeScript Supabase Clerk Stripe, augmented with AI journaling, habit tracking, and progress summaries. This CLAUDE.md template page includes a copyable CLAUDE.md block that you can paste into Claude Code to generate consistent project scaffolding and rules.

Direct answer: This template yields a production ready Claude Code block that defines project role architecture file structure and production rules for the stack.

When to Use This CLAUDE.md Template

• Starting a production ready Mental Wellness Coaching App with the given stack
• Seeking a consistent boilerplate to generate architecture and code scaffolding via Claude Code
• Setting up a data model with journaling entries, habits, and progress summaries in Supabase
• Defining authentication, authorization, and payments flows using Clerk and Stripe
• Establishing validation, security, testing, and deployment rules

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Lead Engineer for a Mental Wellness Coaching App built with Next.js TypeScript Supabase Clerk Stripe AI journaling and habit tracking
Architecture rules:
- Use Next.js app directory with TypeScript Server Components for data access and Client Components for UI
- Use Supabase as primary database with Postgres and Row Level Security enabled on user data
- Use Clerk for authentication and user management support passwordless sign in MFA and session management
- Integrate Stripe for subscriptions and payments verify Stripe webhooks and model webhooks safely
- AI journaling store user entries perform sentiment analysis and feed into progress summaries ensure data privacy and opt in AI usage
- Habit tracking store per user with events and progress visuals
- Progress summaries aggregate weekly monthly KPIs from journals and habits

File structure rules:
- apps web app routes layouts pages
- apps web component UI components
- apps web styles CSS or CSS in JS
- apps web lib shared utilities and types
- apps web services backend interactions with Supabase Clerk Stripe
- apps web hooks custom React hooks
- apps web types TypeScript types
- apps web utils helper functions

Authentication rules:
- Use ClerkProvider at root layout protect pages via withAuth or server actions
- Store JWTs securely and do not expose secrets to client
- Enforce MFA when available and require email passwordless sign in by default

Database rules:
- Use Supabase with Postgres define RLS on journals habits progress_summaries payments subscriptions
- Define foreign keys user_id references auth users id
- Ensure audit columns created_at updated_at

Validation rules:
- Validate incoming data with Zod schemas for API routes and middleware
- Normalize and sanitize user input to prevent XSS SQL injection

Security rules:
- Do not store secrets on the client use environment variables in server code
- Enable CSRF protection on all mutable endpoints
- Enforce content security policy and remote fetch restrictions
- Implement rate limiting for API routes

Testing rules:
- Unit tests with Vitest for utilities and server side validation
- Integration tests with Playwright for critical user flows auth journaling habits progress
- End to end tests should mock external services in CI

Deployment rules:
- Deploy on Vercel with environment variables configured securely
- Use preview deployments for PRs ensure build checks pass
- Enable automatic deployments on main branch

Things Claude must not do:
- Do not hardcode API keys or database credentials
- Do not bypass Supabase Row Level Security
- Do not bypass Clerk authentication or expose session tokens on client
- Do not create insecure endpoints or disable CSRF
- Do not assume Stripe events are always valid without verification

Recommended Project Structure

/apps
  /web
    /app
      /layout.tsx
      /page.tsx
      /components
      /styles
    /lib
    /services
    /types
    /hooks
    /utils
  /packages
  /scripts

Core Engineering Principles

• Type-safety and explicit contracts across frontend and backend (TypeScript, Zod).
• Security-first design: least privilege, proper auth, validated inputs, and encrypted data at rest.
• Clear separation of concerns: UI, domain logic, and data access layers.
• Observability: structured logging, metrics, and tracing for production reliability.
• Be explicit about error handling and failure modes; fail closed on critical operations.

Code Construction Rules

• Follow Next.js app directory conventions; server components for data access, client components for UI.
• All API routes must validate input with Zod; return strict error shapes.
• Use Supabase row-level security (RLS) and policy definitions to enforce access control.
• Store files and assets in appropriate storage (Supabase bucket) when needed; avoid client-side secrets.
• Authentication flows must use Clerk; implement MFA and secure sign-in methods.

Security and Production Rules

• Never expose API keys or secrets in the client bundle; use server-side environment variables.
• Enable CSRF protection on mutable endpoints and use signed webhooks for Stripe.
• Configure proper CORS, content security policy, and secure cookies.
• Introduce server-side rate limits on critical endpoints; monitor for abuse.

Testing Checklist

• Unit tests for utilities and validation schemas (Vitest).
• Integration tests for data access (Supabase) and auth (Clerk).
• End-to-end tests for journaling, habits, and progress flows with Playwright.
• CI should run unit/integration tests and run type checks; ensure build passes.

Common Mistakes to Avoid

• Not enabling Supabase RLS; insecure data access.
• Overexposing Clerk session details on the client.
• Hardcoding Stripe keys or webhook secrets in client code.
• Skipping type validation and input normalization, leading to runtime errors.
• Disabling CSRF or ignoring security headers in API routes.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ

Q1: What is this CLAUDE.md Template for?

A1: It provides a complete, copyable CLAUDE.md template to scaffold a Mental Wellness Coaching App with Next.js TypeScript Supabase Clerk Stripe AI journaling and habit tracking.

Q2: Which stack does it cover?

A2: Next.js TypeScript Supabase (Postgres) Clerk Stripe AI journaling habit tracking and progress summaries.

Q3: How do I use the copyable CLAUDE.md template?

A3: Paste the content into Claude Code and adapt environment specific values and integrate with your project.

Q4: What structure should I follow for my app?

A4: Use a Next.js app directory with a clear separation of UI data access and domain logic; enable RLS and Clerk auth.

Q5: How do I extend for progress summaries?

A5: Build data models for journals and habits, compute weekly monthly aggregates, expose via API and a dashboard UI.