CLAUDE.md Template for a Rental Marketplace with Next.js, TypeScript, Supabase, Clerk, Stripe

Overview

This CLAUDE.md Template is crafted for building a complete Rental Marketplace using Next.js, TypeScript, Supabase, Clerk, Stripe, AI-driven listing creation, an availability calendar, deposits, and a dispute workflow. It provides an actionable, copyable CLAUDE.md block you can paste into Claude Code to bootstrap a production-ready implementation for this stack.

Direct answer: paste the included CLAUDE.md block into your repo to scaffold architecture, file structure, validation, security, and deployment guidelines tailored to a Next.js + TS + Supabase + Clerk + Stripe stack with AI listings and dispute flows.

When to Use This CLAUDE.md Template

• Starting a full-stack rental marketplace using Next.js, TypeScript, Supabase, Clerk, and Stripe.
• Needing a copyable blueprint that configures AI-driven listing creation, availability calendars, deposits, and disputes.
• Seeking an integrated architecture and deployment guide embedded in a Claude Code-ready block.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, a production-grade full-stack architect for a Next.js rental marketplace. You generate a complete CLAUDE.md blueprint and supporting code blocks for a TS + React frontend, Supabase-backed data layer, Clerk-based authentication, Stripe payments, AI-generated listings, availability calendar, deposits, and a dispute workflow.

Architecture rules:
- Tech stack: Next.js (App Router) + TypeScript, Supabase, Clerk, Stripe.
- Data model driven by Supabase; store logic in server components where possible.
- Authentication via Clerk with role-based access: owners can manage listings; renters can book; admins can resolve disputes.
- Payments via Stripe: holds/deposits as separate PaymentIntents; webhooks for status updates.
- AI features: use a dedicated AI service for listing generation and enrichment; store results in listings table and audit with a version field.
- Availability calendar: normalized availability per listing; bookings check conflicts.
- Deposits and disputes: hold deposit on payment, escrow state machine; disputes logged and routed to admin via queue.
- Security: never ship secrets in client; use environment variables; enforce Row Level Security on Supabase; verify webhook signatures.
- Performance: prefer SSR for critical flows; use client components only where interactive UI is required.
- Access controls: enforce roles at API boundaries; protect Stripe/webhook endpoints.

File structure rules:
- apps/web/src/app for routes and UI
- apps/web/src/app/listings for listing pages
- apps/web/src/app/checkout for booking and payments
- apps/web/src/components shared UI
- apps/web/src/lib for integrations (supabaseClient, clerkClient)
- apps/web/src/public for assets
- environment variables via .env.local with proper prefixes

Authentication rules:
- Use ClerkProvider at the root; require user session for protected routes
- Owner: account role 'owner' can CRUD listings
- Renter: role 'renter' can create bookings and leave reviews
- Validate session on server side for all API routes

Database rules:
- Tables: users, listings, availability, bookings, deposits, disputes, payments, AIListings
- Row Level Security enabled; policies enforce that only authorized roles can read/write
- Timestamps and id fields are UUIDs; prefer server-generated timestamps
- Listings include fields: id, owner_id, title, description, price_per_night, location, images, ai_generated=False, ai_version, created_at, updated_at
- Availability: listing_id, start_date, end_date, available
- Bookings: id, listing_id, user_id, start_date, end_date, status
- Deposits: id, booking_id, amount, currency, status, created_at
- Disputes: id, booking_id, reason, status, created_at
- Payments: id, booking_id, payment_intent_id, amount, status
- AIListings: id, listing_id, prompt_used, model, created_at

Validation rules:
- Validate all inputs on server
- Price and dates must be valid; end_date after start_date
- Images must be valid URLs
- AI generation prompts must be controlled and logged

Security rules:
- Do not expose API keys; store in environment variables
- Validate Stripe webhook signatures
- Use CSRF protection for POST routes
- Enforce content security policy and strict same-origin policies
- Do not bypass Clerk for protected routes

Testing rules:
- Unit tests for utilities and validators
- Integration tests for API routes: listings, bookings, deposits, disputes
- End-to-end tests for booking flow and dispute resolution
- CI should run TS type checks, lint, unit tests, integration tests

Deployment rules:
- Deploy to Vercel with environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY, STRIPE_SECRET_KEY
- Use webhooks for Stripe; verify signatures
- Enable server-side rendering for listings pages; static generation for public pages
- Use caching for listing results; invalidation on changes

Things Claude must not do:
- Do not hard-code secrets in code
- Do not bypass server-side checks or Clerk authentication
- Do not block legitimate rental operations for perf gains
- Do not skip input validation for bookings or payments
- Do not implement client-side only deposits escrow logic
- Do not use non-production AI prompts or unsafe content generation

Recommended Project Structure

/
├── apps
│   └── web
│       ├── src
│       │   ├── app
│       │   │   ├── layout.tsx
│       │   │   ├── listing
│       │   │   │   ├── [id]
│       │   │   │   │   └── page.tsx
│       │   │   │   └── page.tsx
│       │   │   └── checkout
│       │   │       └── page.tsx
│       │   ├── components
│       │   │   ├── ListingCard.tsx
│       │   │   ├── Calendar.tsx
│       │   │   └── PaymentButton.tsx
│       │   ├── lib
│       │   │   ├── supabaseClient.ts
│       │   │   └── clerkClient.ts
│       │   └── styles
│       │       └── globals.css
│       ├── next.config.js
│       └── tsconfig.json
│   public/
│       └── images
│           └── placeholder.png
└── README.md

Core Engineering Principles

• Explicit contracts and typed interfaces across API boundaries
• Secure by default: proper auth, validation, and least privilege
• Data correctness with server-side validation and DB constraints
• Incremental, testable changes with CI checks
• Performance focus: SSR for listing pages, caching, and streaming where possible

Code Construction Rules

• Use TypeScript everywhere; avoid any where possible
• Prefer server components for data fetching; keep client components lean
• Wrap Stripe payments with a server API and validate all parameters server-side
• AI generation only via a controlled endpoint; audit prompts and store prompts used
• Use Supabase for data; enable RLS and define policies
• All API routes must verify Clerk sessions before proceeding

Security and Production Rules

• Keep secrets in environment variables; never commit to repo
• Validate Stripe signatures and webhook events
• Enable CORS for approved origins; enforce CSRF on mutating routes
• Apply Content Security Policy; restrict inline scripts
• Monitor for anomalies; implement rate limiting on booking creation

Testing Checklist

• Unit tests for validators and utilities
• Integration tests for /listings, /bookings, /payments endpoints
• End-to-end tests: browsing listings, AI-generated listing, booking with calendar, deposits, and disputes
• CI: type checks, lint, unit tests, integration tests

Common Mistakes to Avoid

• Assuming client-side validation is sufficient
• Exposing secret keys or using environmentless config in UI
• Skipping webhook validation or using insecure endpoints
• Hard-coding price calculations on the client
• Neglecting accessibility and internationalization in listing UI

Related implementation resources: AI Use Case for Surf Schools Using Wave Forecast Models To Automatically Schedule Lesson Times for The Upcoming Week and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ

• What is CLAUDE.md Template? A copyable blueprint to scaffold a complete stack for a rental marketplace using Claude Code.
• What tech stack does this template target? Next.js with TypeScript, Supabase, Clerk, Stripe, plus AI listing generation features.
• Can Claude generate the AI listings? Yes, via a controlled AI endpoint that creates and enriches listings while logging prompts.
• How are deposits handled? Deposits are held via Stripe with an escrow workflow and webhook-driven updates.
• How do I secure the application? Use Clerk for auth, Supabase RLS, environment vars, webhook signature checks, and CSP.