CLAUDE.md Template: Next.js, TypeScript, Supabase, Clerk, Stripe for Manufacturing Quality SaaS

Overview

CLAUDE.md template is a ready-to-paste Claude Code blueprint designed for building a full Manufacturing Quality SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI defect detection, batch records, and root cause analysis. It provides concrete instructions you can paste into CLAUDE.md to initialize project rules and guardrails.

Direct answer: This CLAUDE.md Template gives you a complete set of Claude Code instructions, a stack-specific file structure, and production-ready guardrails tailored to a manufacturing QA SaaS.

When to Use This CLAUDE.md Template

• Starting a Manufacturing Quality SaaS with Next.js and TypeScript front-end and Supabase back-end.
• Setting up Clerk authentication and Stripe billing in a single template.
• Implementing AI defect detection and batch records with root-cause analysis.
• Wanting a copyable CLAUDE.md to lock in architecture decisions and avoid drift.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Platform Engineer building a Manufacturing Quality SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI defect detection, batch records, and root cause analysis.

Architecture rules:
- Use Next.js App Router, with a dedicated portal app in apps/portal.
- Supabase for database and auth; Clerk for session management and fine-grained RBAC; Stripe for billing.
- All data processing occurs server-side when possible; client components call server actions.
- AI defect detection integration: call a secured AI endpoint; handle latency and retries; store results in database.

File structure rules:
- apps/portal/app/ (Next.js app)
- apps/portal/components/
- lib/ (shared services: supabase.ts, clerk.ts, stripe.ts)
- db/ (migrations, schema)
- scripts/ (deploy and test scripts)
- environment variables: NEXT_PUBLIC_*, SECRET_*

Authentication rules:
- Clerk handles sign-in/up; use ClerkProvider at the root.
- Enforce RBAC: admin, engineer, operator, viewer.
- Use server actions for protected operations; validate session on each request.

Database rules:
- Supabase Postgres with Row Level Security enabled.
- Tables: users, organizations, batches, defects, batch_records, root_causes, audit_logs, subscriptions.
- Policies to restrict reads/writes by role and tenant; enforce foreign keys.

Validation rules:
- Validate all inputs with Zod on both client and server sides.
- Strictly type API routes with return types.

Security rules:
- Do not expose secret keys; read from environment only.
- Verify Stripe webhooks with signature; validate all external calls.
- Enable CSRF protection for forms and sensitive actions.

Testing rules:
- Unit tests for utilities; integration tests for API routes; end-to-end tests for critical user journeys.
- Use Playwright for E2E; run tests in CI before deploy.

Deployment rules:
- Deploy to Vercel; set Stripe webhook URL; run migrations on deploy; enable linting and type checking in CI.
- Use environment-specific configs; rotate secrets; monitor error budgets.

Things Claude must not do:
- Do not bypass authentication or RBAC.
- Do not perform privileged DB admin actions.
- Do not bypass validation or risk exposing secrets.
- Do not implement custom AI logic outside secured endpoints without approval.

Recommended Project Structure

manufacturing-quality-saas/
├── apps/
│   └── portal/
│       ├── app/
│       │   ├── layout.tsx
│       │   └── page.tsx
│       ├── components/
│       ├── hooks/
│       └── styles/
├── db/
│   ├── migrations/
│   └── schema.sql
├── lib/
│   ├── supabase.ts
│   ├── clerk.ts
│   └── stripe.ts
├── scripts/
├── package.json
├── tsconfig.json

Core Engineering Principles

• Strong typing and explicit contracts across UI and API boundaries.
• Least privilege: RBAC and Row-Level Security enforced everywhere.
• Idempotent, deterministic server actions with clear error handling.
• Separation of concerns between UI, business logic, and data access.
• Observability: structured logging, metrics, and tracing in production.
• Automated tests, CI checks, and repeatable deployments.

Code Construction Rules

• Use TypeScript everywhere; define runtime schemas with Zod; infer types from schemas when possible.
• Client calls server actions for data mutations; avoid direct database access from the client.
• Store secrets only in environment variables; never commit secrets to source control.
• All API routes and server actions must return typed responses.
• Define data models for batches, defects, and root causes with explicit relations.
• Use Stripe webhooks with signature validation; handle events idempotently.
• AI defect detection integration must be behind an authenticated endpoint and rate-limited.
• Do not use non-production databases in development unless explicitly required; mirror production schema.

Security and Production Rules

• RBAC enforced via Clerk roles and Supabase RLS; enforce tenant isolation.
• Protect API endpoints with middleware that validates sessions and roles.
• Rotate secrets; store in Vercel/K8s secret stores; monitor for exposure.
• Validate all inputs; sanitize outputs; avoid reflection or injection vulnerabilities.
• Enable CSRF protection for forms and sensitive actions.
• Stripe webhooks verified; use idempotent processing.
• Audit logs for critical actions and data changes.

Testing Checklist

• Unit tests for utilities and helpers.
• Integration tests for API routes (auth, batches, defects).
• End-to-end tests for user journeys (login, create batch, run AI check, view root cause analysis).
• CI checks: lint, type-check, tests; pre-deploy checks.
• Deployment smoke tests in staging; monitor error budgets.

Common Mistakes to Avoid

• Assuming client can perform privileged DB writes; always use server-side actions.
• Ignoring RBAC and failing to secure rows with RLS policies.
• Overusing AI for non-critical decisions; ensure auditability of AI results.
• Disabling necessary validations or skipping webhook verification.

Related implementation resources: AI Agent Use Case for Injection Molding SMEs Using Temperature and Defect Logs to Identify Root Causes Of Rejected Batches and Server-side atomic operators for safe production edits in AI pipelines.

FAQ