CLAUDE.md Template: Next.js 14 + Supabase + Clerk + Stripe Booking App

Overview


CLAUDE.md template for building a complete Home Services Booking App with Next.js 14, TypeScript, Supabase, Clerk, Stripe, AI quote generation, scheduling, and a provider dashboard. This page is a copyable CLAUDE.md template designed for Claude Code to produce a production-ready implementation for this stack. Direct answer: This template defines roles, architecture, file structure, auth, data model, validation, security, tests, deployment, and missteps to avoid for a robust Home Services booking experience.



When to Use This CLAUDE.md Template



  - Starting a new Home Services booking app using Next.js 14, TypeScript, Supabase, Clerk, Stripe, and a provider dashboard.

  - Seeking an opinionated, deployment-ready Claude Code starting point with concrete rules and directory structure.

  - Need detailed security, testing, and deployment guidance tailored to a modern stack with payments and scheduling.

  - Want a ready-to-paste CLAUDE.md block to drive development with a single source of truth for the stack.



Copyable CLAUDE.md Template


Copy the block below into CLAUDE.md to drive development for this stack.


# CLAUDE.md

Project role: You are a senior full-stack architect guiding the development of a production-ready Home Services Booking App using Next.js 14, TypeScript, Supabase, Clerk, Stripe, AI quote generation, scheduling, and a provider dashboard.

Architecture rules:
- Use Next.js 14 App Router with server components for data access and client components for UI.
- Centralize business logic in server actions and API routes; keep secret keys on the server.
- Use Clerk for authentication (customers and providers) and role-based access control; implement zero-trust access for sensitive data.
- Supabase as the primary data store; enable Row Level Security (RLS) on all tables and enforce policies in database users.
- Stripe for payments; verify webhook signatures and store payment intents and receipts in the DB.
- AI quote generation runs on the server; never call external AI from the client without server validation.
- All external network calls must be rate-limited and retried using exponential backoff.
- Do not hard-code secrets or API keys; use environment variables managed by the hosting platform.

File structure rules:
- Keep a single source of truth for config in /lib; separate concerns by feature under /src/app for UI and /src/pages for legacy routes if any.
- Use /src/lib/supabaseClient.ts for DB access and /src/lib/stripeClient.ts for payments.
- Place all Clerk components and providers under /src/infra/clerk.
- Put provider-facing pages under /src/app/providers and customer-facing pages under /src/app/bookings.
- Tests under /tests with unit, integration, and e2e suites.

Authentication rules:
- Use Clerk for sign-in/up; require email verification for critical actions.
- Roles: customer, provider, admin. Implement role checks at the API boundary and in server components.
- Protect all API routes; require valid session for actions dealing with bookings, quotes, or payments.

Database rules:
- Supabase Tables: users, providers, customers, services, bookings, quotes, payments, schedules, reviews.
- Enforce RLS policies to restrict booking creation to authenticated customers and provider access only to authorized providers.
- Use foreign keys for relationships and cascading where appropriate (e.g., bookings referencing services, customers, providers).
- Validate data types and constraints at the DB level; enforce defaults for timestamps.

Validation rules:
- Validate all input on the server with a strict schema (e.g., Zod). Type-safe API routes; avoid any-type inputs.
- Normalize strings (trim, case-normalize) and enforce required fields for bookings, quotes, and payments.
- Validate payment details and delivery windows before persisting.

Security rules:
- Secrets must never be exposed to the client. Use runtime config and environment variables.
- Do not trust client-side data; re-validate on server.
- Enforce CSRF protections on state-changing endpoints.
- Use Stripe webhooks securely and verify signatures before updating payments.

Testing rules:
- Unit tests for utility functions and server-side logic (Vitest).
- Integration tests for API routes and DB access (Vitest + supertest or equivalents).
- End-to-end tests for booking flows (Playwright).
- Tests must mock external services (Stripe, AI quotes) in unit tests and integration tests.

Deployment rules:
- Deploy to a hosting platform supporting Next.js 14 App Router (Vercel recommended).
- Configure environment variables securely (NEXT_PUBLIC_ variables for non-sensitive data; SECRET_ for sensitive data).
- Set up Stripe webhooks in the deployment environment and verify signatures.
- Enable automatic builds on code changes and run tests in CI.

Things Claude must not do:
- Do not generate hard-coded secret keys or private tokens.
- Do not bypass authentication checks or permissions.
- Do not call client-side APIs directly from server components without authorization.
- Do not assume user input is valid without server-side validation.
- Do not propose unsafe database migrations or destructive schema changes without caution.

""" End of CLAUDE.md block. Do not modify the stack assumptions."""


Recommended Project Structure


my-app-workspace/
├── apps/
│   └── web/
│       ├── src/
│       │   ├── app/
│       │   │   ├── layout.tsx
│       │   │   ├── route.ts
│       │   │   ├── booking/
│       │   │   │   └── page.tsx
│       │   │   └── providers/
│       │   │       └── page.tsx
│       │   ├── components/
│       │   │   ├── BookingCard.tsx
│       │   │   └── ProviderCard.tsx
│       │   ├── lib/
│       │   │   ├── supabaseClient.ts
│       │   │   ├── stripeClient.ts
│       │   │   └── clerkProvider.tsx
│       │   ├── server/
│       │   │   ├── api/
│       │   │   │   ├── bookings.ts
│       │   │   │   └── payments.ts
│       │   │   └── aiQuotes.ts
│       │   └── styles/
│       └── styles/
├── libs/
│   └── common/
│       └── validators.ts
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
└── README.md


Core Engineering Principles



  - Build for reliability and predictable failure modes.

  - Security by design: enforce proper auth, authorization, and data validation.

  - Data privacy: minimize data exposure and apply least privilege.

  - Clear separation of concerns between UI, business logic, and data access.

  - Observability: structured logging, tracing, and metrics for critical flows.

  - Performance: optimize render paths and server actions; minimize client bundle size.



Code Construction Rules



  - Use TypeScript everywhere; define types for API inputs/outputs and DB models.

  - Keep server-only logic in server components or API routes; avoid leaking DB keys to the client.

  - Use Supabase RLS to enforce data access boundaries; define policies per table.

  - Validate all inputs with a strict schema (e.g., Zod) before persistence.

  - Centralize secrets in environment variables; never commit secrets to source control.

  - Use Stripe webhooks and validate signatures; persist payment status safely.

  - Write tests for critical paths: bookings, payments, and AI quotes.



Security and Production Rules



  - Authenticate all access; enforce roles for customers vs providers.

  - Do not reveal private keys; store in SECRET_ env vars and access via runtime config.

  - Protect endpoints with CSRF tokens for state-changing actions.

  - Regularly rotate API keys and secrets; monitor for unauthorized access.

  - Disable verbose error messages in production; surface generic errors to users.



Testing Checklist



  - Unit tests for utilities, validators, and helpers.

  - Integration tests for API routes and database access with Supabase emulation.

  - End-to-end tests for booking, quoting, scheduling, and provider dashboard flows.

  - Test Stripe webhook handling with simulated events.

  - CI should run all tests on pull requests and fail on any lint or type errors.



Common Mistakes to Avoid



  - Skipping server-side validation; trusting client input.

  - Over-privileging client code with admin or provider rights.

  - Using client secrets or API keys in frontend code.

  - Neglecting Stripe webhook verification and secure webhook handling.

  - Ignoring accessibility and responsive design in the UI for scheduling flows.



Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Why authorization checks belong in AI coding instructions for production-grade systems.





FAQ



  Q: What is this CLAUDE.md Template for?
A: It provides Claude Code instructions to implement a full Home Services Booking App with Next.js 14, TS, Supabase, Clerk, Stripe, AI quotes, scheduling, and provider dashboard.


  Q: Which technologies are covered?
A: Next.js 14, TypeScript, Supabase, Clerk, Stripe, AI quotes, scheduling, and a provider dashboard.


  Q: How do I use the CLAUDE.md Template block?
A: Copy the preformatted CLAUDE.md block into your CLAUDE.md file and adapt environment values and routes to your project.


  Q: How is security handled?
A: Auth uses Clerk; data access is controlled by Supabase RLS; payments via Stripe webhooks; validate all data on the server.


  Q: How do I test this setup?
A: Use Vitest for unit tests, integration tests for API/db, and Playwright for end-to-end booking flows.