CLAUDE.md Template: Next.js, Supabase, Clerk, Stripe Procurement SaaS

Overview

This CLAUDE.md template provides a complete blueprint for building a Procurement Management SaaS using the stack: Next.js, TypeScript, Supabase for data and auth, Clerk for user management, Stripe for payments, plus AI-powered purchase approvals, vendor comparison, and spend analytics. It includes a copyable CLAUDE.md block that you can paste into your project to generate consistent architecture, guardrails, and rules for Claude Code to follow.

Direct answer: Use this CLAUDE.md template when you are architecting a procurement platform that handles vendor data, approvals, spend analytics, and billing within a modern Next.js + Supabase ecosystem, with strict auth via Clerk and payments via Stripe, and AI-assisted decision support.

When to Use This CLAUDE.md Template

• You are building a procurement management SaaS with a focus on approvals, vendor comparison, and spend analytics.
• You require a repeatable CLAUDE.md instruction set that enforces security, architecture, and data rules for a multi-tenant Next.js app.
• You want to integrate AI-based purchase approvals without compromising governance and traceability.
• You rely on Supabase for data storage and authentication and Clerk for user management and SSO.
• You need a ready-to-paste template to kick off development and align the team on file structure and rules.

Copyable CLAUDE.md Template

# CLAUDE.md

- Project role:
  - You are Claude Code acting as the architecture and policy author for a Procurement Management SaaS built with Next.js, TypeScript, Supabase, Clerk, Stripe, AI purchase approvals, and analytics.

- Architecture rules:
  - Use Next.js 14+ app directory with TypeScript strict mode.
  - Supabase handles database and authentication; Clerk handles user sessions and SSO where applicable.
  - Payment workflow is Stripe-based with webhooks verified on the server.
  - All API routes must validate authentication and enforce role-based access: admin, procurement-manager, finance.
  - All AI decisions must be auditable and reversible; log AI prompts and responses.
  - Use server components where possible; keep client components lean.
  - Do not mix client-side secrets; fetch secrets only on the server.

- File structure rules:
  - app/
    - page.tsx
    - layout.tsx
    - globals.css
    - /purchase-requests
    - /vendors
    - /analytics
    - /ai-approvals
    - /checkout
    - /components
    - /lib
      - supabase.ts
      - stripe.ts
    - /providers
      - ClerkProvider.tsx
    - /utils
  - components/ shared UI components
  - lib/ server utilities, DB client starter, Stripe, and Clerk adapters
  - types/ domain models

- Authentication rules:
  - Use Clerk for frontend authentication and session management.
  - Verify Clerk tokens on protected API routes; tie Clerk roles to procurement roles.
  - Require email verification for admin access; implement 2FA where feasible.
  - Store user-specific tenant data in Supabase with RLS per tenant.

- Database rules:
  - Data model: vendors, procurements, approvals, orders, spend_analytics, users, roles.
  - Enable Row Level Security (RLS) on all tables; policies must enforce tenant isolation and role checks.
  - Avoid hard-coding secrets in database; use environment variables.
  - Use foreign keys for referential integrity between procurements, approvals, and vendors.

- Validation rules:
  - Use Zod schema validation for all inputs (server side preferred).
  - Validate vendor IDs, procurement IDs, amounts, currencies, and user permissions.
  - Normalize currency codes and amounts to cents (integer) for Stripe charges and analytics.

- Security rules:
  - Do not expose API keys or secret tokens to the client.
  - Validate Stripe webhook signatures; reject invalid payloads.
  - Enforce least privilege in Stripe and Supabase service roles.
  - Log security events and alert on anomalies (failed auth, unusual access patterns).

- Testing rules:
  - Unit tests for service layers (auth, vendor matching, approvals, analytics calculations).
  - Integration tests for API routes (auth gating, stripe webhook, procurement flows).
  - End-to-end tests covering vendor search, approval flow, and analytics dashboards.

- Deployment rules:
  - Deploy to a modern hosting platform supporting Next.js (e.g., Vercel) with server and edge runtimes.
  - Configure environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET, STRIPE_SECRET, WEBHOOK_SECRET.
  - Run CI checks: type checks, unit tests, and linting before merge.
  - Enable observability: error monitoring and performance tracing.

- Things Claude must not do:
  - Do not bypass authentication or authorization checks.
  - Do not perform unvalidated destructive actions in production data.
  - Do not store plaintext secrets on the client.
  - Do not rely on client-side validation alone for security-critical flows.

Recommended Project Structure

app/
  layout.tsx
  page.tsx
  globals.css
  /purchase-requests
  /vendors
  /analytics
  /ai-approvals
  /checkout
  /components
  /lib
    supabase.ts
    stripe.ts
  /providers
    ClerkProvider.tsx
  /utils

# Optional (for monorepos)
packages/
  procurement-frontend/
    (same as app/ above for the Next.js frontend)
  procurement-api/
    (server-side adapters and API routes)

Core Engineering Principles

• Single source of truth: centralize data models and access patterns in Supabase with clear domain boundaries.
• Security-by-default: enforce authentication, authorization, and data access rules at the API boundary and database level (RLS).
• Explicit contracts: define strict input/output shapes with TypeScript types and Zod schemas.
• Observability: structured logging, metrics, and traces for procurement and AI decisions.
• Iterative deployment: small, safe feature toggles and feature flags for risk-managed releases.

Code Construction Rules

• Implement server components for data fetching and keep client components UI-focused.
• Use TypeScript strict mode; avoid any where possible; ensure all API routes are typed.
• Use Supabase for data and auth; map to Clerk roles for UI access control.
• Stripe integration in server-side code; verify webhook signatures; store payment intents in analytics.
• AI purchase approvals must be auditable: log prompts, model responses, and final decisions.
• Validation first: validate all inputs server-side with Zod; sanitize data before DB or API calls.
• Do not hard-code credentials; use environment variables and secret managers.

Security and Production Rules

• Never expose secret keys to the client; use server routes for sensitive actions.
• Enable Supabase RLS and define per-tenant policies; enforce procurement roles (admin, procurement-manager, finance).
• Verify Stripe webhooks with a secret and replay protection.
• Audit AI-driven approvals with immutable logs and versioned prompts.
• Regularly rotate API keys and monitor for anomalous access patterns.

Testing Checklist

• Unit tests for auth, vendor matching, approvals, and analytics calculations.
• Integration tests for API routes, including Stripe webhook and procurement flow.
• End-to-end tests for vendor search, approval decision, and checkout flow.
• Performance tests on procurement analytics dashboards.
• Security tests: access controls and data leakage checks.

Common Mistakes to Avoid

• Omitting tenant isolation or RBAC in database policies.
• Trusting client-side validation for security-critical paths.
• Storing secrets in client code or public repos.
• Neglecting AI decision auditability and traceability.
• Ignoring Stripe webhook replay protection and signature verification.

Related implementation resources: AI Agent Use Case for Wholesalers Using Multi-Currency Ledger Trackers To Calculate Foreign Exchange Risk Exposure Across Global Accounts and The Consultants Toolkit for Client Portals: Building Reusable Agents with Governance.

FAQ