CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe for Restaurant SaaS

Overview

A CLAUDE.md Template page for building a complete Restaurant Ordering SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI menu generation, delivery tracking, and a kitchen dashboard. This page provides a copyable CLAUDE.md block and a stack-aligned project structure for rapid development.

When to Use This CLAUDE.md Template

• When you need a ready-to-paste Claude Code block for Next.js + TS + Supabase + Clerk + Stripe with AI menu generation.
• To standardize architecture across multiple restaurant apps sharing the same stack.
• To onboard new developers quickly with a complete, copyable CLAUDE.md template.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are the lead Architect for a Restaurant Ordering SaaS built with Next.js, TypeScript, Supabase, Clerk, Stripe, AI menu generation, delivery tracking, and a kitchen dashboard.

Architecture rules:
- Use Next.js App Router with TypeScript
- Supabase for DB, auth, and storage; Clerk for identity; Stripe for payments
- Server Components for data loading; Client Components for interactivity
- Clear domain modules: restaurant, menu, order, delivery, kitchen, payments
- Expose secure API routes under /api with robust input validation

File structure rules:
- Monorepo with apps/web and apps/api
- src/domains with subfolders: restaurant, menu, order, delivery, kitchen, payments
- components, hooks, lib shared under apps/web/src
- tests for unit/integration under tests/ with clear naming

Authentication rules:
- Clerk handles sign-in/sign-up; sessions validated on API routes
- Enforce tenant boundaries; use server-side guards for sensitive data access

Database rules:
- Supabase Postgres with tables: restaurants, menus, menu_items, orders, deliveries, kitchens, payments, users
- Implement Row Level Security policies for all sensitive tables
- Use proper foreign keys and created_at/updated_at timestamps

Validation rules:
- Zod-based schemas for Restaurant, Menu, MenuItem, Order, Delivery, Payment
- Validate currency, status enums, addresses, and schema shapes

Security rules:
- Do not hard-code secrets; use environment variables
- Enforce HTTPS; enable CORS with strict origins
- Do not bypass auth or RBAC checks on API routes

Testing rules:
- Unit tests for utilities and schemas
- Integration tests for API routes with a mock Supabase client
- End-to-end tests for order flow with Playwright

Deployment rules:
- Deploy to Vercel; set SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_API_KEY, STRIPE_SECRET, OPENAI_API_KEY in environment
- Run type checks, lint, tests in CI; migrate DB safely in production

Things Claude must not do:
- Do not access production data; do not bypass authentication; do not reveal secrets or keys; do not perform real payments in non-prod.

Recommended Project Structure

restaurant-saas/
  apps/
    web/
      app/
        layout.tsx
        page.tsx
      components/
      hooks/
      lib/
      styles/
    api/
      src/
        routes/
        services/
  libs/
    db/          # Supabase client and DB helpers
    auth/        # Clerk integration, JWT helpers
    payments/    # Stripe integration, webhooks
    delivery/    # Delivery tracking logic
    ai/          # AI menu generation utility and models
  shared/
    schemas/

Core Engineering Principles

• Strong typing and explicit contracts across UI, API, and DB layers
• Clear domain boundaries for restaurant, menu, orders, deliveries, and kitchens
• Idempotent operations and safe rollbacks
• Secure by default: RBAC, RBAC policies, input validation, and secret management

Code Construction Rules

• Prefer server components for data fetching; keep client components lean
• Use Zod for all input validation and export schemas for reuse
• Do not bypass Clerk or RBAC checks on protected routes
• Write modular, testable units with clear interfaces

Security and Production Rules

• Enable Supabase Row Level Security and policies for all sensitive tables
• Store secrets in environment variables; never commit them
• Validate Stripe webhooks and signer on the API boundary

Testing Checklist

• Unit tests for utilities and schemas
• Integration tests for API routes with a mock Supabase client
• End-to-end tests for the entire order flow using Playwright

Common Mistakes to Avoid

• Relying on client-side validation for critical data
• Skipping RBAC and RBAC policies in database rules
• Overfetching in API routes and leaking data

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ

• What stack does this CLAUDE.md Template cover? Next.js, TypeScript, Supabase, Clerk, Stripe, AI menu generation, delivery tracking, and a kitchen dashboard.
• How is AI menu generation integrated? Through dedicated API routes and background workers using a safe AI service.
• How is delivery tracking handled? Real-time status updates via DB events and optional WebSocket/SSE delivery streams with RBAC guards.
• How do I deploy? Vercel or similar with environment variables for Supabase, Clerk, Stripe, and AI keys.
• What about security? Enforce RBAC, TLS, rotate secrets, and restrict data access by tenant and role.