CLAUDE.md Template: Warehouse WMS with Next.js, TS, Supabase, Clerk, Stripe

Overview

CLAUDE.md Template for building a complete Warehouse Management SaaS (WMS) using Next.js, TypeScript, Supabase, Clerk, Stripe, AI picking forecasts, inventory alerts, and order dashboards. This template targets a multi-tenant SaaS architecture and guides Claude Code to produce reliable, secure code for the stack.

Direct answer: This CLAUDE.md Template provides concrete Claude Code instructions to implement core WMS features with the requested stack, including authentication, data models, and dashboards.

When to Use This CLAUDE.md Template

• When you are building a multi-tenant Warehouse Management SaaS with real-time inventory and orders.
• When you need AI-assisted picking forecasts and inventory alerts integrated with dashboards.
• When you require a TypeScript-first UI with a Next.js app using Supabase as the backend and Clerk for authentication.
• When Stripe is required for subscription and payments alongside secure user management.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior software engineer building a Warehouse Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, AI picking forecasts, inventory alerts, and order dashboards. You must produce clean, production-ready code blocks and follow the architecture rules exactly.

Architecture rules:
- Use Next.js App Router with server components for data fetching where possible.
- Use Supabase as the primary data backend; enable RLS and set up policies.
- Use Clerk for authentication and user management; enforce roles: admin, inventory_manager, warehouse_worker, customer.
- Payment handling via Stripe; use webhooks for events; do not expose secret keys in frontend code.
- All code must be type-safe TypeScript; prefer TS interfaces and types.

File structure rules:
- Keep a single source-of-truth in /apps/warehouse-app
- /apps/warehouse-app/app (UI route handlers)
- /apps/warehouse-app/components
- /apps/warehouse-app/lib
- /apps/warehouse-app/db
- /apps/warehouse-app/api
- /libs (shared utilities)
- /types (shared TS types)

Authentication rules:
- All API routes must verify Clerk session; enforce roles
- Use Clerk provider in app entry
- Never trust client-side data; verify on server

Database rules:
- Supabase with Postgres; enable RLS
- Tables: warehouses, products, inventory, orders, forecasts, alerts, users
- Policies: proper access controls by tenant_id; employees can read inventory within their warehouses; tenants isolated

Validation rules:
- Validate all mutations on server with runtime schema (e.g., zod)
- Ensure required fields present; numeric ranges validated

Security rules:
- Do not leak keys; do not log secrets on prod
- Use CSRF tokens for write operations
- Encrypt sensitive data at rest if possible

Testing rules:
- Unit tests for UI components; integration tests for API endpoints; e2e tests for UI flows
- Use Playwright for end-to-end; use Vitest for unit tests

Deployment rules:
- Deploy to Vercel or similar; set environment variables: SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET_KEY, STRIPE_SECRET_KEY
- CI should run tests; perform linting
- Use semantic versioning for releases

Things Claude must not do:
- Do not bypass authentication
- Do not hardcode secrets
- Do not bypass Supabase RLS
- Do not assume single-tenant data isolation
- Do not introduce insecure endpoints

Recommended Project Structure

warehouse-app/
├─ app/
│  ├─ layout.tsx
│  ├─ page.tsx
│  ├─ dashboard/
│  │  ├─ page.tsx
│  │  └─ components/
│  ├─ inventory/
│  │  └─ page.tsx
│  ├─ orders/
│  │  └─ page.tsx
│  └─ forecasts/
│     └─ page.tsx
├─ components/
├─ lib/
├─ db/
├─ services/
├─ styles/
├─ types/

Core Engineering Principles

• Type-safe by design: TS everywhere, clear interfaces, and explicit types for data models.
• Single source of truth: lean on Supabase for data, with RLS and strong policies to isolate tenants.
• Security by design: Clerk-based auth, CSRF protection, secret management, and auditability.
• Composable architecture: modular UI with server components and thin client state management.
• Observability and reliability: structured logging, metrics for inventory and order flows, and automated tests.

Code Construction Rules

• Use Next.js App Router with TS; separate UI, API, and server logic.
• Access Supabase from server components; never embed secrets in the client.
• Validate inputs on both client and server; prefer runtime schemas (e.g., zod) on server routes.
• Enforce Clerk authentication on all data-modifying operations; check roles in server handlers.
• Put business rules in server code and database policies in Supabase; avoid duplicating logic on clients.
• Keep components focused; use small, testable units with explicit props.

Security and Production Rules

• Enable Row-Level Security in Supabase; create tenant-scoped policies for inventories, orders, and forecasts.
• Do not expose private keys or service keys to the frontend; use environment variables and secure vaults.
• Use Stripe webhooks to process subscription events; verify signatures server-side.
• Use Clerk for authentication; enforce role-based access on API routes.
• Implement CSRF protection for write endpoints; log security events and monitor anomalies.

Testing Checklist

• Unit tests for UI components and utility functions.
• Integration tests for API routes and database interactions (with Supabase test data).
• End-to-end tests for core flows (inventory updates, forecasting, orders, and dashboards).
• CI runs linting, type checks, and test suites; ensure fast feedback loops.
• Production parity tests including versioned deployments and rollback checks.

Common Mistakes to Avoid

• Skipping Supabase RLS and exposing data across tenants.
• Storing secrets in client-side code or environment files without protection.
• Assuming single-tenant data isolation in middleware or queries.
• Overcomplicating the data model; ignore edge cases without testing.
• Forgetting to validate input on the server side.

Related implementation resources: AI Agent Use Case for Industrial Supply Distributors Using Invoice Tracking To Flag Accounts Facing Stock-Out Patterns and Production-grade billing logic governed by project rules.

FAQ

What is the purpose of this CLAUDE.md Template?

To provide a concrete, copyable Claude Code instruction block for building a WMS with the listed stack, including auth, data models, AI forecasts, and dashboards.

Which stack does this CLAUDE.md Template cover?

Next.js, TypeScript, Supabase, Clerk, Stripe, AI forecasting, inventory alerts, and order dashboards.

How should authentication and authorization be handled?

Use Clerk for authentication; enforce roles on both API routes and server components, ensuring server-side validation of access.

What are key deployment considerations?

Deploy to a platform like Vercel; configure SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET_KEY, STRIPE_SECRET_KEY; enable automated tests and linting.

What should Claude not do?

Do not bypass authentication, leak secrets, bypass Supabase RLS or assume single-tenant data isolation, or introduce insecure endpoints.