CLAUDE.md Template for Restaurant Operations SaaS (Next.js, TS, Supabase, Clerk, Stripe)

Overview

A CLAUDE.md template for building a complete Restaurant Operations SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, with AI inventory planning, menu analytics, and staff scheduling. This page is a ready-to-paste CLAUDE.md template that yields a production-ready Claude Code block tailored to a Next.js + TS stack and multi-tenant data model. Direct answer: paste the CLAUDE.md template content below into a CLAUDE.md file to generate a guided implementation for a full-stack restaurant ops platform.

When to Use This CLAUDE.md Template

• Starting a production-grade Restaurant Ops SaaS with modern frontend and a scalable backend.
• Seeking a repeatable Claude Code pattern for Next.js, TypeScript, Supabase, Clerk, Stripe integration, and AI features.
• Implementing multi-tenant data isolation and role-based access control for restaurant operators, managers, and staff.
• Integrating AI-driven inventory planning and menu analytics into operational workflows.
• Setting up reliable deployment, testing, and security guidelines from day one.

Copyable CLAUDE.md Template

# CLAUDE.md

// CLAUDE CODE BLOCK FOR: Restaurant Operations SaaS (Next.js + TS + Supabase + Clerk + Stripe + AI Inventory + Menu Analytics + Scheduling)

Project role: You are a senior full‑stack engineer leading a multi‑tenant restaurant operations SaaS; your directives are to generate production‑ready code blocks that respect security, performance, and maintainability.

Architecture rules:
- Multi‑tenant Postgres on Supabase with Row Level Security (RLS) per restaurant tenant.
- Next.js 14 App Router with TypeScript, Server Components, and Client Components where appropriate.
- Clerk for authentication and user provisioning; tokens validated on API routes.
- Supabase as the single source of truth for data; use supabase-js in server and client contexts.
- Stripe for subscriptions; handle webhooks securely; support per-restaurant billing plans.
- AI modules (inventory planning, menu analytics) powered by Claude Code prompts that call external AI APIs when needed.
- Prefer server-side rendering for data-heavy pages; minimize client bundle size.
- Use environment-based feature flags to enable/disable experimental features.

File structure rules:
- Follow a clear separation: app/ (UI), server/ (API routes & business logic), lib/ (shared utilities), features/ (domain-specific modules), infra/ (db/schema, migrations, secrets).
- Do not colocate business logic in React components; create service modules in server/ or lib/.
- All API routes must be in app/api/ with TS types; avoid ad‑hoc routes.

Authentication rules:
- Clerk handles sign‑in/sign‑up; store minimal Clerk IDs in users table.
- Enforce tenant context on every request via server middleware that injects tenantId from user claims.
- Do not trust client data; validate on server and enforce RBAC rules.

Database rules:
- Supabase Postgres with tables: restaurants, users, staff, menus, ingredients, inventory, inventory_adjustments, orders, order_items, analytics, schedules, shifts, tasks, subscriptions, invoices.
- Implement RLS: restaurant_id as the tenant key; restrict rows per tenant.
- Use foreign keys with ON DELETE CASCADE where appropriate for tenant isolation.
- Index critical query columns: restaurant_id, staff_id, inventory_id, analytic_date.

Validation rules:
- Validate inputs with a shared Zod schema; export types for API routes and UI layers.
- Sanitize all strings; prohibit raw SQL in client code.

Security rules:
- Never expose secrets in the client bundle; fetch secrets from server routes.
- Use CSRF tokens for state-changing operations on the client.
- Validate Stripe webhooks with signatures; store only necessary data from webhooks.
- Enforce TLS everywhere; implement HSTS in production.

Testing rules:
- Unit tests for domain services with Vitest.
- Integration tests for API routes using supertest or Playwright for end-to-end flows.
- Mock external API calls (AI, payment) in tests.

Deployment rules:
- Deploy with Vercel or your cloud provider; configure env vars: NEXT_PUBLIC_* for client, SECRET_* for server; set Stripe webhook secret; Clerk keys; SUPABASE_URL/ANON_KEY.
- Enable automatic deployments on PRs; run CI tests before merge.
- Set up monitoring; log errors with structured JSON; alert on payment/webhook failures.

Things Claude must not do:
- Do not bypass server validation or access tokens on the client.
- Do not perform direct DB writes from the client without a server API gate.
- Do not assume a single tenant is the only user; validate tenant context for each request.
- Do not hard‑code secrets or API keys in the Claude guidance.

Recommended Project Structure

apps/web/
├─ app/
│  ├─ layout.tsx
│  ├─ page.tsx
│  ├─ globals.css
│  ├─ components/
│  │  ├─ Layout.tsx
│  │  ├─ Navbar.tsx
│  │  ├─ Sidebar.tsx
│  │  └─ widgets/
│  ├─ features/
│  │  ├─ inventory/
│  │  │  ├─ InventoryProvider.tsx
│  │  │  ├─ InventoryPage.tsx
│  │  │  └─ inventoryUtils.ts
│  │  ├─ menu/
│  │  │  ├─ MenuPage.tsx
│  │  │  └─ analytics.ts
│  │  ├─ scheduling/
│  │  │  ├─ SchedulePage.tsx
│  │  │  └─ shifts.ts
│  │  └─ analytics/
│  │     ├─ RevenueChart.tsx
│  │     └─ KPI.ts
│  ├─ lib/
│  │  ├─ apiClient.ts
│  │  └─ prismaLike.ts
│  ├─ services/
│  │  ├─ supabase.ts
│  │  ├─ clerk.ts
│  │  └─ stripe.ts
│  └─ hooks/
│     ├─ useTenant.ts
│     └─ useAuth.ts
├─ next.config.js
├─ package.json
├─ tsconfig.json
└─ env.example

infra/
├─ migrations/
│  ├─ 001_init.sql
│  └─ 002_add_restaurant_tables.sql
└─ schema.sql

Core Engineering Principles

• Tenant-first architecture with strict RBAC and data isolation.
• End‑to‑end type safety across UI, API, and database layers.
• Explicit data contracts and clear boundaries between domain features.
• Security‑first by default: validate input, enforce authorization, and protect secrets.
• Observability: structured logs, metrics, and tracing for request paths and AI suggestions.

Code Construction Rules

• Use Next.js App Router with TypeScript; separate server and client components; avoid serverless edge pitfalls.
• All DB access goes through server-side API routes; never access Supabase directly from the client for writes.
• Leverage Clerk for authentication and maintain tenant context on every request.
• Define strict Zod schemas for all inputs; export types for reuse across UI and API layers.
• Model AI prompts as modular functions with clear input/output contracts; cache results when appropriate.
• Adhere to a minimal public surface; expose only necessary endpoints and keep keys in server envs.
• Keep Stripe integration isolated behind a payments service with secure webhook handling.

Security and Production Rules

• Enable Supabase Row Level Security (RLS) with tenant_id policies; review all policies regularly.
• Validate Clerk JWTs on server routes; enforce per‑tenant access controls on every query.
• Store secrets in a dedicated secret store; never commit to VCS.
• Use CSRF protection for state-changing operations; implement same-origin policies for API endpoints.
• Validate and log all Stripe webhook events; verify signatures and replay protection.
• Use TLS, HSTS, and secure cookies; rotate credentials periodically.

Testing Checklist

• Unit tests: domain services, data validation, and AI prompt builders with Vitest.
• Integration tests: API routes, Stripe webhook endpoints, Clerk auth flow.
• End‑to‑end tests: user onboarding, restaurant creation, inventory updates, and scheduling flows using Playwright.
• Security tests: RBAC, tenant isolation, and secret leakage checks.
• Deployment checks: environment variables present, webhooks configured, and healthy health checks.

Common Mistakes to Avoid

• Distributing tenant data without proper RLS policies.
• Mixing client and server logic; performing writes directly from the UI.
• Hard‑coding credentials or API keys in code or prompts.
• Neglecting Stripe webhook replay protection and event validation.
• Underestimating AI prompt management and caching; recomputing identical prompts causes latency.

Related implementation resources: AI Agent Use Case for Cafes Using Pos Data to Identify Best Selling Items By Time Of Day.

FAQ

What is a CLAUDE.md template for this stack?

A copyable CLAUDE.md template that guides Claude Code to scaffold a production‑ready Next.js + TS + Supabase + Clerk + Stripe Restaurant Ops SaaS with AI inventory and analytics.

Can I adapt AI inventory planning to other domains?

Yes. The template provides domain‑agnostic patterns you can tailor to different product data and workflows while maintaining tenant isolation.

How do I secure data with Supabase and Clerk?

Enable RLS on Supabase, validate Clerk tokens on server routes, and enforce RBAC with fine‑grained policies per restaurant.

What should I customize first?

Set up environment variables, connect Clerk and Stripe, initialize Supabase schemas, and tailor inventory analytics schemas to your kitchen.

How do I test and deploy this template?

Use Vitest for unit tests, Playwright for E2E tests, and deploy via Vercel with Stripe webhooks and secret management configured.