Hotel Guest Experience CLAUDE.md Template for Next.js, TypeScript, Supabase, Clerk, Stripe

Overview

A CLAUDE.md template for building a complete Hotel Guest Experience SaaS using the Next.js stack (App Router), TypeScript, Supabase (Postgres), Clerk for authentication, Stripe for payments, AI-driven review analysis, guest messaging, and room service workflows. This page provides a copyable CLAUDE.md block tailored to this stack, plus a stack-specific project scaffold and concrete rules you can paste into Claude Code.

Direct answer: This CLAUDE.md Template encodes rules, project structure, and implementation guidance for a hotel guest experience SaaS built with Next.js, TS, Supabase, Clerk, Stripe, AI review analytics, and guest messaging/room service workflows.

When to Use This CLAUDE.md Template

• You are building a multi-tenant hotel guest experience SaaS with a modern frontend (Next.js) and a TS-first codebase.
• You rely on Supabase for data storage and real-time capabilities, with Clerk for user authentication and Stripe for billing.
• You need AI-powered review analysis, guest messaging, and room service workflows integrated into the platform.
• You require a concrete, paste-ready CLAUDE.md template to guide Claude Code through architecture, security, and deployment considerations.
• You want a stack-specific recommended project structure and rigorous coding rules to prevent architectural drift.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, a software assistant specialized in generating CLAUDE.md templates for modern web stacks. You will produce precise, copy-ready instructions for Next.js + TypeScript + Supabase + Clerk + Stripe hotel SaaS patterns.

Architecture rules:
- Use a Next.js 13+ app directory with server components where appropriate.
- Embrace a clean separation between frontend, API routes, and business logic services.
- Follow a multi-tenant data model in Postgres with clear tenant boundaries at the row level.
- Store secrets in environment variables; never embed secrets in code.
- Centralize business rules in service-layer modules and keep UI components pure.
- Use a single-source of truth for user identity via Clerk tokens; propagate roles securely.
- Prefer stateless API routes and server-side code for sensitive operations.
- Ensure all API routes perform strict input validation and authorization checks.
- Use Stripe webhooks for event-driven billing and reconciliations; validate webhook signatures.

File structure rules:
- Follow a Next.js app router layout with clear feature folders.
- Keep business logic, data access, and integration adapters in separate modules.
- Do not place UI logic in server components; separate React components from server code.
- Example structure (adjust per project):
  hotel-guest-experience/
    apps/
      guest-portal/
        app/
          page.tsx
          layout.tsx
        components/
        styles/
      api/
        [routes].ts
    libs/
      supabase/
        createClient.ts
        db.ts
      clerk/
        client.ts
      stripe/
        webhooks.ts
    services/
      analytics/
      messaging/
      rooms/
    prisma-or-other-ignored-tools-not-used-list (do not include prisma unless used)

Authentication rules:
- Use Clerk for authentication and session management; enforce role-based access: guest, staff, admin.
- On the server, verify Clerk session tokens for protected endpoints.
- Do not store JWTs on client without httpOnly cookies; use Clerk’s recommended patterns.
- When performing privileged actions (billing, room service orders), require a valid Clerk session with appropriate role.

Database rules:
- Tables: hotels, guests, rooms, reservations, reservations_rooms, room_service_orders, messages, ai_reviews, reviews, billing, payments.
- Implement Postgres RLS policies to isolate data per hotel/tenant.
- Use foreign keys to enforce data integrity; index important query fields (hotel_id, guest_id, reservation_id).
- Audit trails for sensitive actions (billing, refunds).

Validation rules:
- Use Zod schemas for all input validation on API routes and form submissions.
- Validate all payloads server-side; never trust client input.
- Normalize data to avoid duplicates (e.g., guest emails, room numbers).

Security rules:
- Do not expose private keys or secrets in client code.
- Validate Stripe webhook signatures; store webhook secret in environment vars.
- CSRF protection on state-changing forms; rely on Clerk-protected endpoints.
- Use HTTPS, secure cookies, and proper CORS policies for API routes.
- Regularly rotate API keys and secrets; implement secret scanning during CI.

Testing rules:
- Unit tests for utility functions and data transformers.
- Component tests with React Testing Library for UI components.
- Integration tests for critical flows (booking, messaging, room service).
- End-to-end tests with Playwright or Cypress for guest journeys.
- CI should fail on unmet test coverage thresholds (e.g., > 80%).

Deployment rules:
- Deploy to a secure environment (e.g., Vercel) with separate prod/staging environments.
- Configure environment variables for Supabase, Clerk, Stripe in the hosting platform.
- Use Stripe webhook endpoint that’s behind a signed secret; test in staging with test keys.
- Enable automatic deployments on PR merges; run tests before deploy.

Things Claude must not do:
- Do not reveal secret keys, API tokens, or database connection strings.
- Do not bypass authentication or authorization checks.
- Do not propose using deprecated or unsupported libraries for the stack.
- Do not create overly broad database permissions or insecure access patterns.
- Do not bypass validation or security controls for convenience.

Recommended Project Structure

hotel-guest-experience/
  apps/
    guest-portal/
      app/
        page.tsx
        layout.tsx
      components/
      styles/
    api/
      (server routes here)
  libs/
    supabase/
      createClient.ts
      db.ts
    clerk/
      client.ts
      server-auth.ts
  services/
    messaging/
      index.ts
    reviews/
      ai-analysis.ts
    room-service/
      orders.ts
  plugins/
    (if applicable; keep minimal and relevant)
  scripts/
    seed-database.ts

Core Engineering Principles

• Clear separation of concerns between frontend, API, and domain services.
• Type safety across frontend and backend with TypeScript and Zod validation.
• Data is owned by hotels (tenants) with strict RBAC and Supabase RLS for isolation.
• Idempotent and auditable critical operations (billing, bookings, room service).
• Automated tests with meaningful coverage and fast feedback loops.

Code Construction Rules

• Use Next.js App Router; keep server components for data access and client components for UI.
• All API routes must validate input with Zod and enforce authorization via Clerk sessions.
• Encapsulate business logic in domain services; avoid duplicating business rules across UI and API layers.
• Leverage Supabase for data storage with Postgres; implement RLS policies per hotel/tenant.
• Integrate Stripe webhooks securely; verify signatures in API routes.
• All secrets live in environment variables; never commit secrets to repo.

Security and Production Rules

• Authenticate all protected endpoints with Clerk; enforce role checks for guest vs staff vs admin.
• Validate and sanitize all input; use server-side validation before any DB write.
• Enable Supabase Row Level Security; create policies per hotel to prevent cross-tenant data leakage.
• Use Stripe webhooks securely; keep webhook secret in environment; log webhook events for audit.
• Configure CSRF protection for state-changing actions; rely on Clerk-authenticated routes.

Testing Checklist

• Unit tests for utility modules and data mappers.
• Component tests for guest-facing UI (booking, messaging, room service).
• Integration tests for API endpoints with Supabase mocks or test databases.
• End-to-end tests covering guest journeys (browse, book, message, order room service).
• CI pipeline runs tests and lints before deployment.

Common Mistakes to Avoid

• Revealing secret keys or embedding credentials in frontend code.
• Skipping RBAC checks or misconfiguring Supabase RLS policies.
• Using client-side code for server-only operations (e.g., billing, secret data).
• Overcomplicating architecture with unused services; keep only necessary components (no Prisma if not used).

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Production-Grade AI Pipelines: Reusable Skill Files and CLAUDE.md Templates.

FAQ