CLAUDE.md template for Salon Booking SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe - CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md template provides a complete Claude Code workflow for building a production-grade Salon Booking SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI demand forecasting, staff calendar, and customer reminders. It defines roles, architecture, file structure, validation, security, testing, deployment, and constraints to ensure a repeatable, scalable build.

What this page is: a copyable CLAUDE.md template page tailored for a Next.js + TypeScript + Supabase + Clerk + Stripe stack with AI forecasting and customer engagement features for salons.

When to Use This CLAUDE.md Template

• You are building a multi-tenant salon booking SaaS with a modern frontend (Next.js) and a scalable backend (Supabase)
• You rely on Clerk for user authentication and fine-grained access control
• You need Stripe for subscriptions and payments, including webhooks and events
• You require AI-based demand forecasting to optimize staffing and scheduling
• You need staff calendars, appointment reminders, and customer notification flows

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Lead full-stack engineer building a production-grade Salon Booking SaaS using Next.js (App Router), TypeScript, Supabase, Clerk, Stripe, AI demand forecasting, staff calendar, and customer reminders.

Architecture rules:
- Use Next.js App Router with server components for data access and server actions for mutations.
- Store data in a Supabase Postgres database with Rows Level Security (RLS) enabled; define policies per table.
- Use Clerk for authentication and user roles; never implement or expose raw auth tokens on the client.
- Integrate Stripe for subscriptions and one-time payments; validate Stripe webhooks with signing secrets.
- Implement AI demand forecasting as a separate service layer that consumes historic data from Supabase and emits forecasted load per timeslot.
- Centralize business logic in server actions and API routes; avoid business logic in React components.
- All sensitive keys must be retrieved from environment variables at runtime; do not hard-code secrets.
- Favor modular services (auth, payments, bookings, forecasting) with clear interfaces.

File structure rules:
- apps/salon-booking/
  - app/
    - layout.tsx
    - page.tsx
    - (route files for booking, forecast, reminders, calendar)
  - components/
  - features/
  - lib/
  - db/
  - services/
  - hooks/
- packages/
  - ui/
  - api/
- scripts/
- tests/

Authentication rules:
- All protected pages must require Clerk session; server components should fetch user info server-side.
- Roles: customer, staff, admin; implement authorization checks on server side for bookings, calendars, and payments.
- Do not perform sensitive operations on the client without a server-auth check.

Database rules:
- Tables: users, salons, staff, bookings, services, calendars, reminders, payments, forecasts
- Primary keys: id; foreign keys: user_id, staff_id, salon_id, booking_id, etc.
- RLS policies enforce: users can read their own bookings; staff can read bookings for their salon; admins can read everything.
- Auditing: include created_at, updated_at, created_by, updated_by.

Validation rules:
- Validate all inputs on the server: required fields, types, formats (email, date strings), and business rules (end times after start times).
- Normalize data (case, trimming) before persisting.
- Use a centralized validator library and schema definitions.

Security rules:
- Use environment variables for all secrets; do not commit keys.
- Validate Stripe signatures and securely handle webhooks.
- Use CORS with a narrow allowed origin for API routes.
- Never leak database connection strings or API keys to the client.

Testing rules:
- Unit tests for domain services: pricing, forecasting calculations, calendar logic.
- Integration tests for API routes (auth, bookings, payments, forecasts).
- End-to-end tests for typical flows (sign-up, create booking, process payment, forecast staffing).
- Mock external services (Stripe, Clerk) in tests.

Deployment rules:
- Deploy on a platform like Vercel; define environment variables for NEXT_PUBLIC_* and SECRET_* values.
- Enable serverless functions with proper timeout and memory limits for forecasting tasks.
- Set up automated tests in CI; run lints and type checks on PRs.

Things Claude must not do:
- Do not reveal keys or secrets in code or logs.
- Do not bypass Clerk authentication in server routes.
- Do not implement client-only logic for server-side operations.
- Do not refer to non-existent APIs or unsupported services without interfaces.
- Do not lock the app to a single vendor-specific feature beyond reasonable abstraction.

Recommended Project Structure

.
├── apps/
│   └── salon-booking/
│       ├── app/
│       │   ├── layout.tsx
│       │   ├── page.tsx
│       │   ├── booking/
│       │   │   ├── page.tsx
│       │   │   └── components/
│       │   ├── forecast/
│       │   │   ├── page.tsx
│       │   │   └── services/
│       │   └── reminders/
│       │       └── page.tsx
│       ├── components/
│       │   └── UI/
│       ├── lib/
│       │   ├── api/
│       │   └── auth/
│       ├── db/
│       │   ├── migrations/
│       │   └── schemas/
│       ├── services/
│       │   ├── payments/
│       │   ├── forecasting/
│       │   └── bookings/
│       └── tests/
├── packages/
│   ├── ui/
│   └── api/
└── scripts/

Core Engineering Principles

• Clear separation of concerns: auth, data access, business logic, and presentation layers must be isolated.
• Type safety across the stack with TypeScript-first development.
• Server-driven validation and security policies (RLS, server actions, and API routes).
• Idempotent, auditable operations for bookings and payments.
• Automated testing and CI for regression prevention.

Code Construction Rules

• Prefer server components for data access; keep client components as lean as possible.
• Use typed API routes and service layers with explicit interfaces.
• All database access must go through a repository/service layer; avoid raw queries in UI code.
• Validate and sanitize inputs server-side; never trust client-provided data beyond initial type checks.
• Forecasting logic must be isolated from core booking logic and configurable via environment-driven endpoints.

Security and Production Rules

• Enable Supabase RLS with per-user policies; audit row-level access and admin privileges.
• Use Clerk for authentication; enforce authorization checks on all protected routes.
• Validate Stripe webhooks with the signing secret and verify event types before processing.
• Store secrets in environment variables; never embed in code or UI.
• Implement robust error handling and monitor for anomalous activity in logs.

Testing Checklist

• Unit tests for domain logic: bookings, pricing, forecasts.
• Integration tests for API endpoints and database interactions with a test database.
• End-to-end tests for user flows: sign-up, create booking, make payment, schedule reminders.
• Security tests: authorization checks, input validation, and webhook verification.
• CI/CD: lint, type checks, tests on PRs; production-like staging environment before release.

Common Mistakes to Avoid

• Exposing secret keys to the client or logs; always use environment variables.
• Skipping row-level security policies and relying on client-side filtering.
• Embedding business logic in React components; keep it in server actions or services.
• Forgetting to validate Stripe webhooks or misconfiguring webhook endpoints.

Related implementation resources: AI Use Case for Surf Schools Using Wave Forecast Models To Automatically Schedule Lesson Times for The Upcoming Week and Why authorization checks belong in AI coding instructions for production-grade systems.

FAQ