CLAUDE.md Template: Repair Shop Management SaaS with Next.js, TS, Supabase, Clerk, Stripe

Overview

The CLAUDE.md template is a copyable Claude Code blueprint for building a complete Repair Shop Management SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and an AI diagnostic assistant. It targets a modern SPA with work orders and invoices.

Direct answer: This CLAUDE.md template provides an end-to-end blueprint that you can paste directly into CLAUDE.md to generate the project scaffolding, API contracts, and deployment rules for the stack.

When to Use This CLAUDE.md Template

• Starting a new Repair Shop SaaS with core modules: customers, vehicles, work orders, invoices, and payments.
• Ensuring consistency, security, testing, and deployment rules across the stack.
• Integrating with Supabase for the database, Clerk for authentication, Stripe for payments, and an AI diagnostic assistant for triage.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are a senior full-stack engineer tasked with implementing a complete Repair Shop Management SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and an AI diagnostic assistant. Your deliverable is production-ready Claude Code blocks suitable for Claude Code. 

Architecture rules:
- Use Next.js App Router with Server Components for data fetch; isolate UI in client components; share common UI libraries.
- Use Supabase Postgres for data; Clerk for authentication; Stripe for payments; AI diagnostic assistant as a separate service endpoint integrated via REST/Webhook.
- Prefer typed API schemas; ensure clear boundaries between domain layers.

File structure rules:
- Place all business logic under apps/repair-shop/ or src/
- src/lib contains DB clients and third-party integrations
- db/schema.sql holds Postgres schema with RLS
- services for domain use cases: work-orders.ts, invoices.ts, ai-diagnostics.ts
- tests/ unit/integration

Authentication rules:
- Use Clerk's Next.js middleware for route protection; check session in server components
- Require strong password, MFA if possible
- Do not expose private keys in client

Database rules:
- Define tables: customers, vehicles, work_orders, invoices, payments, items, ai_diagnostics, users
- Enforce foreign keys; enable RLS with policies for authenticated users
- Use optimistic concurrency via row version if available

Validation rules:
- Use zod schemas for input validation on API routes
- Validate data sizes, formats (emails, dates), and required fields

Security rules:
- Never log secrets; use environment variables; secure cookies; CSRF protection
- Use parameterized queries to avoid SQL injection
- Rate limit critical endpoints

Testing rules:
- Unit tests for services with Vitest; integration tests for API routes; end-to-end tests with Playwright
- Mock external calls (Stripe, AI service)

Deployment rules:
- CI should run type checks, lint, tests
- Deploy to Vercel/Supabase; ensure environment variables for Clerk, Stripe, and AI endpoints
- Include health checks and rollback plan

Things Claude must not do:
- Do not bypass authentication checks
- Do not generate raw SQL with string concatenation
- Do not store secrets in code or in client
- Do not assume external network access without citing allowances

Recommended Project Structure

.
├── apps/
│   └── repair-shop/
│       ├── app/
│       │   ├── layout.tsx
│       │   └── page.tsx
│       │   └── dashboard/
│       │       └── page.tsx
│       ├── components/
│       ├── lib/
│       └── services/
├── db/
│   └── schema.sql
├── src/
│   ├── lib/
│   ├── services/
│   └── components/
└── tests/

Core Engineering Principles

• Typed contracts and explicit API boundaries between client and server.
• Server Components first with progressive hydration for interactivity.
• Security by design: least privilege, proper auth, and enforced data access rules.
• Single source of truth for domain models and database schema.
• Test automation: unit, integration, and end-to-end tests in CI.
• Observability: structured logging, tracing, and metrics for critical paths.

Code Construction Rules

• Use TypeScript everywhere; define DTOs with strict types for API boundaries.
• API routes should validate input with Zod schemas; export types for reuse.
• Database access via a typed client; avoid raw string SQL in app code.
• Auth is Clerk-based; check sessions in server components and API routes.
• Payments integrated through Stripe SDK; handle webhooks securely.
• AI diagnostic integration via a dedicated service with clear rate limits and fallback.
• Do not hard-code secrets; use environment variables and secret managers.
• Ensure 404/403 handling and consistent error responses from APIs.

Security and Production Rules

• Enable Postgres Row-Level Security (RLS) and policies for all tables.
• Secure cookies, CSRF protection, and server-only secret handling.
• Use parameterized queries or ORM to avoid SQL injection; never build SQL via string concatenation.
• Audit logging for critical actions (payments, invoices, user roles).
• Automated health checks, canary deployments, and rollback plans in CI/CD.

Testing Checklist

• Unit tests for services (work orders, invoices, AI diagnostics) with Vitest.
• Integration tests for API routes; ensure end-to-end flows (create work order → generate invoice → pay).
• Playwright or Cypress tests for UI flows in the Repair Shop app.
• Security tests: auth flows, access control, and input validation.

Common Mistakes to Avoid

• Ignoring Row-Level Security or misconfiguring policies.
• Storing secrets in client code or repository.
• Skipping input validation leading to invalid data states.
• Overreliance on client-side validation for critical paths.
• Forgetting to test Stripe webhooks in a staging environment.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ