CLAUDE.md Template: Grocery Delivery SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe

Overview

CLAUDE.md template for a complete Grocery Delivery SaaS built with Next.js, TypeScript, Supabase, Clerk, Stripe, and integrated modules for inventory sync, AI demand forecasting, and driver management. This page is a copyable CLAUDE.md template you can paste directly into a CLAUDE.md file to bootstrap your project.

Direct answer: Use this CLAUDE.md Template to scaffold a production-ready stack that combines a modern frontend (Next.js + TS) with a scalable backend (Supabase) and the core business modules you need to ship a grocery delivery service quickly.

When to Use This CLAUDE.md Template

• You are building a Grocery Delivery SaaS with Next.js, TypeScript, and a Postgres backend.
• You need integrated auth (Clerk), payments (Stripe), inventory sync, and driver management.
• You want a reproducible starting point with clear architecture, file layout, and Claude Code rules.
• You require guidance on security, testing, and deployment for production environments.

Copyable CLAUDE.md Template

# CLAUDE.md

- Project role: Architect a production-ready Grocery Delivery SaaS using Next.js (App Router), TypeScript, Supabase as the data backend, Clerk for authentication, and Stripe for payments. Include inventory sync, AI demand forecasting, and driver management.

- Architecture rules:
  - Use a monorepo structure with a dedicated frontend (Next.js) and shared services.
  - Prefer server components for data access; protect API routes with Clerk authentication and server-side checks.
  - Centralize business logic in services/ with clean API layers to database.
  - Ensure idempotent operations for inventory updates and order processing.

- File structure rules:
  - apps/web: Next.js frontend
  - apps/web/services: integration modules for Clerk, Stripe, Supabase
  - apps/web/components: UI components
  - infra/supabase: DB schema and migrations
  - ai/forecasting: forecasting models and integration points
  - drivers/management: driver assignment logic

- Authentication rules:
  - Clerk handles authentication; roles: customer, merchant, admin, driver
  - Enforce server-only access tokens; check role on API routes
  - Use protected routes and server actions for sensitive operations

- Database rules:
  - Tables: users, roles, stores, products, inventory, orders, payments, shipments, drivers, forecasts
  - Enable Supabase RLS and create policies per table; grant appropriate roles
  - Use foreign keys and proper indexes for query performance

- Validation rules:
  - Use Zod schemas for all API inputs
  - Validate on server and client where appropriate
  - Enforce type safety and string length limits

- Security rules:
  - Do not expose API keys in frontend code
  - Use environment variables and secret vault integrations
  - Implement CSRF protection; use SameSite cookies; restrict CORS

- Testing rules:
  - Unit tests for services and utilities
  - Integration tests for API endpoints and DB interactions
  - End-to-end tests for checkout, inventory updates, and driver assignment

- Deployment rules:
  - Deploy frontend on Vercel or similar; backend is serverless via Next.js API routes
  - CI must run lint, type checks, tests, and build
  - Secrets rotation and monitoring in production

- Things Claude must not do:
  - Do not bypass authentication or authorization checks
  - Do not reveal secrets in logs or UI
  - Do not hard-code sensitive keys
  - Do not rely on deprecated APIs or outdated Stripe versions
  - Do not implement client-side business logic that compromises security

Recommended Project Structure

grocery-delivery-saas/
├── apps/
│   └── web/
│       ├── app/
│       │   ├── layout.tsx
│       │   └── page.tsx
│       ├── components/
│       ├── lib/
│       ├── services/
│       │   ├── clerk.ts
│       │   ├── stripe.ts
│       │   ├── supabase.ts
│       │   ├── inventory.ts
│       │   ├── forecasting.ts
│       │   └── driver.ts
│       └── styles/
├── infra/
│   └── supabase/
│       ├── migrations/
│       │   └── 2026-01-01_init.sql
│       └── seeds/
│           └── seed.sql

Core Engineering Principles

• Clear separation of concerns between frontend, business logic, and data access.
• Security-first by default: auth, authorization, and data validation on the server.
• Type safety: end-to-end type definitions across API surfaces and database schemas.
• Observability: structured logging, metrics, and error reporting integrated with deployment.
• Reliability: idempotent operations and retry-safe patterns for inventory and payments.

Code Construction Rules

• Use Next.js App Router with server components for data access; client components only where necessary.
• Supabase as the source of truth; define Row Level Security policies; avoid client-side DB access.
• All API inputs validated with Zod; types generated from schemas where possible.
• Stripe integration through server-side endpoints; verify webhooks using signature verification.
• Inventory sync should debounce rapid updates and reflect in UI via real-time subscriptions.
• AI demand forecasting integrated as separate service that consumes sales data and outputs forecasts; store results in a dedicated forecasts table.
• Driver management should support queue-based assignments with retry for failed deliveries.

Security and Production Rules

• Enable Supabase RLS and write policies for all sensitive tables (inventory, orders, payments).
• Use Clerk for authentication; enforce role-based access in API routes.
• Verify Stripe webhook signatures; keep webhook endpoints server-side only.
• Store secrets in a vault; do not hard-code in code or logs.
• Enforce TLS, SSO, and secure cookies; apply CSP where applicable.

Testing Checklist

• Unit tests for services, utilities, and validators.
• Integration tests for Clerk auth, Supabase DB operations, and Stripe flows.
• End-to-end tests for checkout, order lifecycle, inventory updates, and driver assignment.
• Deployment tests to verify secrets are loaded and endpoints are accessible in production-like environments.

Common Mistakes to Avoid

• Relying on client-side security for critical operations.
• Skipping DB security policies (RLS) or over-permissive policies.
• Mixing business logic into UI components instead of service layers.
• Hard-coding environment variables; failing to rotate secrets.

Related implementation resources: AI Use Case for Airbnb Hosts Using Guesty To Dynamically Adjust Nightly Pricing Based On Local Events.

FAQ

• What is included in this CLAUDE.md Template? A copyable CLAUDE.md block with architecture rules, file structure, authentication, database, validation, security, testing, deployment, and do-not-do guidelines for a Next.js + TS + Supabase + Clerk + Stripe Grocery Delivery SaaS.
• Which stack is covered? Next.js with TypeScript for the frontend, Supabase as the backend data store, Clerk for authentication, Stripe for payments, plus modules for inventory sync, forecasting, and drivers.
• Can I adapt this template for other domains? Yes. The CLAUDE.md block provides framework-level rules you can adjust for different product domains, data models, and business flows.
• How do I deploy this? Follow the deployment rules in the CLAUDE.md block; typically deploy the Next.js frontend to Vercel or similar and host serverless API routes, ensure secrets are secured.
• How do I customize roles and permissions? Modify Clerk roles and update Supabase RLS policies and API route guards to enforce the required access levels.