CLAUDE.md Template: Next.js + TypeScript Service Marketplace with Supabase, Clerk, Stripe, AI Matching, Bookings, Reviews, Payouts

Overview


CLAUDE.md template for building a complete Service Marketplace using Next.js, TypeScript, Supabase, Clerk, Stripe, AI provider matching, bookings, reviews, and payout management. It includes a copyable CLAUDE.md block you can paste into CLAUDE.md to enforce architecture, rules, and best practices for this stack.


Direct answer: A production ready blueprint for a Next.js + TypeScript marketplace with Supabase as the backend, Clerk for auth, Stripe for payments, and a modular AI matching layer for provider selection, with end to end flows for bookings, reviews, and payouts.



When to Use This CLAUDE.md Template



  - You are building a multi vendor service marketplace with real time availability and payments.

  - You need a repeatable, audit friendly CLAUDE.md that codifies architecture decisions and constraints.

  - You want a single source of truth for auth, payments, and AI driven provider matching during development and onboarding.

  - You require explicit deployment and security rules to reduce drift between environments.



Copyable CLAUDE.md Template


Copy and paste the block below into CLAUDE.md in your repository to lock the stack decisions and implementation guardrails.


# CLAUDE.md
Project Role: You are Claude Code, an expert assistant for building production grade Next.js TypeScript marketplaces using Supabase, Clerk, Stripe, and an AI provider matching layer. Provide precise, testable instructions that you can paste into code and run tests against.

Architecture Rules:
- Build a Next.js 13+ app with App Router using TypeScript
- Primary data store: Supabase Postgres with Row Level Security enabled
- Authentication: Clerk for user auth and session management
- Payments: Stripe for checkout, subscriptions, and payouts
- AI Provider Matching: a modular service (lib/aiMatcher.ts) that selects an optimal provider based on constraints
- Domains: auth, marketplace, bookings, reviews, payouts, ai-matching
- Prefer server components for data fetching and client components for UI
- Use environment variables for all secrets; never embed in client code

File Structure Rules:
- apps/marketplace/app/ as the Next.js application root
- lib/ for clients (supabaseClient.ts, clerkClient.ts, stripeClient.ts, aiMatcher.ts)
- services/ for business logic (bookingService.ts, listingService.ts, payoutService.ts, reviewService.ts)
- components/ for UI components
- models/ or types/ for TypeScript interfaces
- tests/ for unit and integration tests

Authentication Rules:
- Use ClerkProvider with server actions for protected routes
- Store sessions and tokens in HTTP-only cookies
- Protect sensitive API routes with server side checks

Database Rules:
- Supabase Postgres with tables: users, listings, bookings, payments, reviews, payouts, ai_matches
- Enable Row Level Security policies for all sensitive tables
- Example policies:
  - listings.owner_id = auth.uid()
  - bookings.user_id = auth.uid() OR admin
- Use foreign keys and referential integrity; never delete referenced rows without cascade where appropriate

Validation Rules:
- Validate all inputs with strict TypeScript types and runtime schemas (e.g., Zod-like)
- Normalize and deduplicate inputs
- Return deterministic error messages for known failure modes

Security Rules:
- Verify Stripe webhooks using the signature header
- Do not log sensitive payloads in production
- Enforce CSRF protection for state changing operations
- Don’t expose admin credentials in client code

Testing Rules:
- Unit tests for services and utilities (tests/unit)
- Integration tests for API routes and DB (tests/integration)
- End-to-end tests for core flows (booking, payment, payouts) (tests/e2e)

Deployment Rules:
- Frontend: Vercel or equivalent with proper env vars
- Backend: Supabase project with configured anon and service keys
- Webhooks: Stripe webhooks deployed and secured
- Secret management via environment configuration; never commit secrets

Things Claude Must Not Do:
- Do not bypass server side validation
- Do not generate insecure payment flows or bypass Clerk auth
- Do not embed secrets in client code


Recommended Project Structure


projects/
  marketplace/
    app/
      layout.tsx
      page.tsx
      globals.css
    lib/
      supabase.ts
      clerk.ts
      stripe.ts
      aiMatcher.ts
    services/
      bookingService.ts
      listingService.ts
      paymentService.ts
      reviewService.ts
      payoutService.ts
    components/
      ListingCard.tsx
      BookingWidget.tsx
    types/
      index.ts
    tests/
      unit/
      integration/


Core Engineering Principles



  - Type safety and explicit contracts with TypeScript

  - Clear separation of concerns across domains

  - Security by design with least privilege

  - Idempotence and robust error handling

  - Observability through structured logging and metrics



Code Construction Rules



  - Write small, testable functions with clear inputs and outputs

  - Adopt Next.js App Router with server components where appropriate

  - Validate all API inputs with strict schemas

  - Enforce Row Level Security in Supabase for all data access

  - UI components should be presentational; data should be supplied via props

  - Explicitly type API responses and database rows



Security and Production Rules



  - Store secrets in environment variables and secret managers

  - Validate Stripe webhooks with the official signature

  - Implement strict CORS and CSRF protections

  - Apply access controls on admin routes and sensitive actions

  - Redact sensitive data in logs and telemetry



Testing Checklist



  - Unit tests for services and utilities

  - Integration tests for DB interactions via Supabase

  - End-to-end tests for core journeys: booking, payment, and payout

  - CI/CD deployment smoke tests



Common Mistakes to Avoid



  - Exposing private keys in client code

  - Relying on client-side validation alone

  - Skipping Supabase Row Level Security policies



Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Clear project instructions enable reliable one-click demo workflows for production AI.





FAQ



  What stack does this CLAUDE.md Template cover?
  Next.js, TypeScript, Supabase, Clerk, Stripe, AI provider matching, bookings, reviews, payouts.
  How do I use the copyable CLAUDE.md Template?
  Copy the block and paste into CLAUDE.md, then adjust environment values and endpoints for your project.
  How are payments managed?
  Stripe is used for checkout, subscriptions, and payouts; set up webhooks and verify signatures.
  How does AI provider matching work?
  An AI provider matching service in lib/aiMatcher.ts selects providers based on user constraints and availability.
  What are the recommended deployment steps?
  Deploy frontend to Vercel/Netlify; configure Supabase, Clerk, and Stripe webhooks; manage secrets via environment variables.