CLAUDE.md Template: Next.js Fitness Studio SaaS with TypeScript, Supabase, Clerk, Stripe

Overview

The CLAUDE.md template is a copyable instruction set designed for Claude Code to scaffold a complete Fitness Studio SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI driven workout plans, memberships, and class bookings. This template targets a full stack architecture with a modern frontend, secure auth, payments, data layer, and AI services integrated via Claude Code blocks.

When to Use This CLAUDE.md Template

• When you need a ready to paste CLAUDE.md block to scaffold a fitness SaaS with the listed stack
• When you want architecture rules, file structure guidance, and deployment considerations baked in
• When you require stack specific security, validation, and integration guidelines

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, an AI assistant that designs and scaffolds a complete Fitness Studio SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI workout plans, memberships, and class booking. You write precise, copyable code generation instructions for a developer to paste into CLAUDE.md.

Architecture rules:
- Use a modular, layered architecture with clear separation of concerns: frontend, auth, payments, data access, and AI services.
- Tech stack: Next.js (App Router), TypeScript, Supabase (Postgres), Clerk for authentication, Stripe for payments. AI features powered by built in Claude Code blocks.
- Prefer server components for data fetching logic; keep client components lean.
- Do not rely on Prisma, Mongoose, Drizzle, or other ORMs not part of this template.
- All server secrets must be accessed via environment variables, not hard coded.

File structure rules:
- Place all code under apps/fitness-studio/ with app/, components/, lib/, features/, and services/ directories.
- Do not create obsolete tech folders like prisma/, mongoose/, or drizzle/.
- Use a conventional Next.js 14 app directory structure with route based code organization.
- Ensure type safety with strict TypeScript config; export types for API boundaries.

Authentication rules:
- Integrate Clerk for authentication; support sign in / up and session management.
- Use Clerk middleware to protect protected routes; ensure public pages for marketing exist.
- Do not bypass authentication for any protected data APIs.

Database rules:
- Use Supabase for Postgres; define tables: users, memberships, workouts, plans, bookings, payments, ai_plans.
- Enforce row level security where appropriate; use Postgres policies.
- Validate all inputs at the API boundary; never trust client input.

Validation rules:
- Validate API payloads using Zod schemas; return 400 on invalid data.

Security rules:
- Do not expose secret keys in client bundles; load from environment variables.
- Enable CSRF protection on auth flows; validate webhook signatures from Stripe.
- Use signed cookies for sessions where appropriate.

Testing rules:
- Provide unit tests for services, hooks, and utilities; integration tests for auth and payments flows; end-to-end tests for bookings.

Deployment rules:
- Deploy to Vercel or similar; configure env vars for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_API_URL, CLERK_FRONTEND_API, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET.
- Include Stripe webhook handling in serverless functions; ensure idempotent processing.

Things Claude must not do:
- Do not write insecure code or reveal private keys; do not implement client-only payment flows without server validation.
- Do not bypass authentication or authorization checks.
- Do not generate ORM migrations outside the provided stack pattern.

Recommended Project Structure

apps/
  fitness-studio/
    app/
      layout.tsx
      page.tsx
      globals.css
      components/
        ui/
          Button.tsx
          Card.tsx
        layout/
          Header.tsx
      features/
        auth/
          SignIn.tsx
          SignUp.tsx
        bookings/
          BookingPage.tsx
        memberships/
          Plans.tsx
        workouts/
          AIPlan.tsx
        payments/
          Checkout.tsx
      hooks/
        useUser.ts
        useBookings.ts
      lib/
        supabase.ts
        clerk.ts
        stripe.ts
        ai.ts
        validators.ts
    public/
    styles/
    utils/

Core Engineering Principles

• Principle of least privilege: restrict data access by role and policy in Supabase and API routes.
• Explicit boundaries: separate UI, API, and AI logic; avoid cross-cutting concerns.
• Idempotent operations: all mutate operations should be idempotent or have clear reconciliation paths.
• Type-safe contracts: define and reuse TypeScript interfaces for all API data shapes.
• Security-first mindset: never expose secrets; validate inputs; secure webhooks.

Code Construction Rules

• All code must be TypeScript; avoid any implicit any.
• Use strict type checking and defined API schemas (eg Zod) for requests and responses.
• Do not hard-code configuration; use environment variables.
• Claude must generate reusable components and hooks; favor composition over inheritance.
• Do not generate ORM migrations outside the provided stack pattern.
• Keep components accessible; ensure keyboard navigation and ARIA labels where applicable.
• Do not rely on client-side secrets; fetch sensitive data on the server.

Security and Production Rules

• Enable CSRF protection on auth flows; verify Stripe webhooks with the secret.
• Use signed cookies for sessions; store session tokens server-side where possible.
• Configure rate limiting on critical endpoints; monitor for abuse.
• Rotate keys and secrets regularly; use a secrets manager if available.

Testing Checklist

• Unit tests for API handlers and utilities; mock external services (Supabase, Stripe).
• Integration tests for auth, memberships, and bookings flows.
• End-to-end tests for user signup, plan purchase, and class booking scenarios.
• CI should run type checks, lint, and test suites on push.

Common Mistakes to Avoid

• Relying on client-side authorization for sensitive data; always enforce server-side checks.
• Overfetching data; implement precise queries and pagination.
• Using non-deterministic AI outputs; sanitize and validate generated workout plans.

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

Q: What is a CLAUDE.md Template?

A: A copyable instruction block for Claude Code to scaffold stack-specific templates.

Q: Which stack does this template cover?

A: Next.js with TypeScript, Supabase, Clerk, Stripe for a Fitness Studio SaaS with AI-powered workouts and class bookings.

Q: How do I customize this template for my project?

A: Modify the code block to reflect project naming, environment variables, and domain; keep architecture rules and security guidelines.

Q: Can Claude configure Stripe webhooks and payments?

A: Yes; the template includes deployment and webhook validation instructions.

Q: Where do I paste the CLAUDE.md template?

A: In a CLAUDE.md file at the root of your project as instructed by the template.