CLAUDE.md Template: Next.js Inventory Forecasting SaaS with Supabase, Clerk, and Stripe (CLAUDE.md template)

Overview

CLAUDE.md template for building a complete Inventory Forecasting SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI reorder planning, demand prediction, and stock alerts. This page is a copyable CLAUDE.md template you can paste directly into a CLAUDE.md file to generate a production-ready blueprint for the stack.

Direct answer: This CLAUDE.md template provides a structured, codified guide to deliver an end-to-end inventory forecasting platform with AI-driven reorder planning, using Next.js with TypeScript, Supabase for data, Clerk for authentication, and Stripe for payments. Claude Code can execute each block to generate consistent boilerplate, models, and workflows.

When to Use This CLAUDE.md Template

• You are building a multi-tenant inventory forecasting SaaS using Next.js and TypeScript.
• You need tight integration with Supabase for data storage and auth flows.
• You want Clerk for authentication and user management with role-based access.
• You require Stripe for subscriptions, invoicing, and webhook validation.
• You incorporate AI reorder planning and demand prediction to optimize stock levels.
• You must implement robust validation, security, and deployment rules for production readiness.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Platform Architect for an Inventory Forecasting SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and Claude Code
Architecture rules:
- Build with Next.js app router and server components where possible
- Use Supabase as the sole database, authentication, and row-level security base
- Use Clerk for user authentication and session management
- Use Stripe for subscriptions and payments; validate webhooks server-side
- Expose a set of typed REST endpoints for inventory data and forecasts
- AI components for reorder planning and demand forecasting should run in server components or edge functions where appropriate
- All data model changes should be versioned and auditable
- Do not bypass authentication or authorization rules

File structure rules:
- Use a conventional Next.js app with app dir structure
- Centralize domain logic under src/lib, src/server, and src/app modules
- Separate UI components from business logic; keep API routes pure and typed
- Use a models folder for TypeScript interfaces and types exported across the app
- Do not use non-TS types for core business logic

Authentication rules:
- Clerk handles user sign-in, sign-up, and sessions
- Use server-side guards for sensitive API routes based on Clerk roles
- Do not expose private Clerk tokens to the client

Database rules:
- Supabase Postgres with RLS enabled
- All sensitive data stored securely; use Row Level Security policies per table
- Use stored procedures or edge functions for critical operations
- Do not perform raw string concatenation for SQL in server code

Validation rules:
- Use TypeScript types for all entities
- Runtime validation with a schema library (e.g., zod) for API boundaries
- Validate incoming webhook payloads from Stripe with signatures

Security rules:
- Do not commit secrets; use environment variables managed by a secret manager
- Enforce CSRF protection on state-changing API routes where appropriate
- Validate Stripe webhooks and Clerk sessions on all payment-related endpoints
- Implement rate limiting and anomaly detection on API endpoints

Testing rules:
- Unit tests for business logic with strict type coverage
- Integration tests for API routes and payment flows
- End-to-end tests for user signup, login, and policy enforcement
- CI should run lint, type checks, and tests on push/PR

Deployment rules:
- Deploy to a serverless hosting platform suitable for Next.js (eg, Vercel or equivalent)
- Configure environment variables securely; wire Stripe webhooks to a protected endpoint
- Enable observability with logs and metrics; monitor for latency and error rates
- Do not deploy without approved CI status checks

Things Claude must not do:
- Do not bypass Clerk or Stripe verification steps
- Do not generate insecure database queries or expose secrets
- Do not ship client-side secrets or private keys
- Do not assume database migrations are free of conflicts; always test in staging

Recommended Project Structure

inventory-forecast/
├─ app/
│  ├─ layout.tsx
│  ├─ page.tsx
│  └─ inventory/
│     └─ page.tsx
├─ components/
├─ lib/
│  ├─ supabase.ts
│  ├─ clerk.ts
│  └─ stripe.ts
├─ models/
│  └─ index.ts
├─ pages/
│  └─ api/
│     ├─ webhook/
│     └─ stripe.ts
├─ services/
│  └─ forecast.ts
├─ styles/
│  └─ globals.css
└─ utils/
   └─ validators.ts

Core Engineering Principles

• Single source of truth for data and UI state
• Typed boundaries between client and server with strict TS types
• Idempotent operations and deterministic deployments
• Security by default with proper authentication, authorization, and validation
• Observability: structured logs, metrics, and tracing
• Secure handling of secrets and credentials

Code Construction Rules

• Use TypeScript throughout; enable strict mode; no implicit any
• Follow Next.js app router conventions; server components for data access
• All API routes are typed with input validation and proper error handling
• Supabase usage via a single client wrapper with bound environment keys
• Stripe webhooks validated with signature verification; avoid trusting client-side payloads
• AI reorder and demand prediction should be modularized as server-side services
• Do not inline secrets or keys in code; use environment variables and secret management

Security and Production Rules

• Enable Clerk session checks on protected endpoints
• Enable Supabase RLS policies per table and audit changes
• Validate Stripe signatures for all webhook endpoints
• Use server-side type-safe endpoints to avoid leakage of internal data
• Implement rate limiting and input validation to prevent abuse
• Perform regular dependency and vulnerability scanning as part of CI

Testing Checklist

• Unit tests for data models and helpers
• Integration tests for API routes with Supabase mocks
• End-to-end tests for authentication, checkout, and basic flows
• Regression tests for AI forecast logic
• Deployment checks: environment variables, webhook endpoints, and secrets rotation

Common Mistakes to Avoid

• Hardcoding secrets or using client-side keys in the frontend
• Skipping server-side validation and RBAC checks
• Ignoring Supabase RLS and overexposing data via API routes
• Neglecting webhook verification for Stripe
• Overusing client state for forecast calculations; keep heavy logic server-side

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

FAQ

What stack does this CLAUDE.md Template cover?

The template targets Next.js with TypeScript, Supabase, Clerk, Stripe, and integrated AI reorder planning and demand prediction.

How do I use the Copyable CLAUDE.md Template block?

Copy the entire block under Copyable CLAUDE.md Template into a CLAUDE.md file in your repo and run Claude Code to expand the scaffolding.

What authentication and authorization are included?

Clerk handles authentication; server-side guards enforce authorization on protected routes and API endpoints.

How are AI features integrated?

AI reorder planning and demand forecasting are implemented as server-side services that consume inventory data and forecast results.

What are deployment considerations?

Deploy on a serverless platform with proper secret management, webhook endpoints, and observability in place.