CLAUDE.md Template: Field Service Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe

Overview

A CLAUDE.md template page for building a complete Field Service Management SaaS. This stack uses Next.js with TypeScript for the frontend, Supabase for the backend and authentication, Clerk for identity, Stripe for payments, and Claude Code-driven AI for job assignment, technician notes, and customer updates. It provides a practical, copyable CLAUDE.md template you can paste into your project to bootstrap the architecture, rules, and workflows.

Direct answer: This CLAUDE.md Template encodes a production-ready blueprint for a field-service SaaS stack, including auth, database, payments, AI routing, and customer/technician workflows, all in a consistent Claude Code block you can reuse.

When to Use This CLAUDE.md Template

• You’re building a Field Service Management SaaS with a modern frontend and robust backend.
• You need integrated auth (Clerk), a relational database (Supabase), and payments (Stripe).
• You want AI-assisted job routing and real-time customer/technician updates with auditability.
• You require a concrete project structure, validation, security, and deployment rules that are Claude-friendly.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role:
- You are Claude Code, an AI assistant that generates production-ready Claude Code templates for a Next.js + TypeScript + Supabase + Clerk + Stripe stack focused on Field Service Management (FSM).

Architecture Rules:
- Monorepo layout with three primary domains: fsm-frontend (Next.js UI), fsm-backend (Next.js API/routes or Node service), fsm-ai (AI orchestration and worker services).
- Supabase used as Postgres database and authentication layer; Clerk for client authentication; Stripe for subscriptions/payments; AI job assignment module interacts via REST/WS.
- Use a single source of truth for business data; ensure strict separation of concerns between UI, business logic, and data access.
- All API calls must be authenticated; serverless functions must verify Clerk sessions and Supabase tokens.
- Prefer edge caching for read-heavy endpoints; write operations should hit a trusted API route that enforces business rules.
- Use environment-specific configs for dev/stage/prod and rotate keys via secret managers.

File Structure Rules:
- apps/fsm-frontend/ (Next.js UI, pages/, components/, hooks/, lib/ with supabase.ts, clerk.ts, stripe.ts)
- apps/fsm-backend/ (API routes or Node service, server code, services/ with stripe.ts, clerk.ts listeners, autoscalers)
- apps/fsm-ai/ (AI orchestration, worker.ts, job-queue.ts, ai-rules.ts)
- libs/types/ (shared TypeScript types and Zod schemas)
- libs/ui/ (design system components)

Authentication Rules:
- Clerk handles user sign-in/sign-up on the frontend; verify Clerk sessions on protected API routes.
- Use Supabase Row Level Security (RLS) with policies for users, customers, technicians, and jobs.
- Do not expose API keys or service roles to the client; use service role only on server-side.

Database Rules:
- Tables: users, customers, technicians, jobs, notes, updates, payments, subscriptions, audit_logs.
- Enforce foreign keys and RLS; every job has an assigned technician and a customer; status tracked with history.
- Use appropriate indexes for query patterns (jobs by status, technician, customer, SLA dates).

Validation Rules:
- Use Zod schemas for all request bodies and API responses.
- Normalize input (trim, lowercase where appropriate); enforce required fields for job creation and status updates.

Security Rules:
- Do not hard-code secrets; store them in environment variables; validate all inputs; sanitize outputs to avoid leaks.
- Implement CSRF protection for state-changing endpoints when necessary.
- Enforce TLS, CSP, and secure cookies; audit all admin actions.

Testing Rules:
- Unit tests for all business logic in fsm-backend and fsm-ai; integration tests for API routes; end-to-end tests for critical user journeys.
- Mock Clerk and Supabase calls; verify authorization behavior and error handling.

Deployment Rules:
- Deploy frontend on Vercel; backend and AI services on a scalable host (Edge Functions or Node workers); Stripe webhooks configured.
- Configure environment variables securely; enable automatic redeploys on code changes; monitor error budgets.

Things Claude Must Not Do:
- Do not create insecure admin endpoints or embed private keys in code.
- Do not assume a single tenant model unless explicitly supported by your Supabase schema.
- Do not bypass Clerk or Supabase authorization checks.

Recommended Project Structure

.
├── apps/
│   ├── fsm-frontend/        # Next.js UI (TypeScript)
│   │   ├── src/
│   │   │   ├── pages/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── lib/
│   │   │   │   ├── supabase.ts
│   │   │   │   ├── clerk.ts
│   │   │   │   └── stripe.ts
│   │   │   ├── services/
│   │   │   └── types/
│   │   └── next.config.js
│   ├── fsm-backend/          # API routes or Node service
│   │   ├── src/
│   │   │   ├── routes/
│   │   │   ├── lib/
│   │   │   └── services/
│   │   └── tsconfig.json
│   └── fsm-ai/               # AI orchestration and worker services
│       ├── src/
│       │   ├── jobs/
│       │   ├── ai/
│       │   └── utils/
│       └── package.json
└── libs/
    ├── types/                 # Shared TS types and Zod schemas
    └── ui/                    # Design system components

Core Engineering Principles

• Clear separation of concerns between UI, business logic, and data access.
• Strong typing with TypeScript across frontend and backend; enforce data contracts with Zod.
• Security-first by default: authenticated endpoints, proper RBAC/RLS, and secrets managed via environment variables.
• Single source of truth for business data; avoid duplicating state across services.
• Observability: structured logging, metrics, and error monitoring for all critical flows.

Code Construction Rules

• Frontend must use Next.js with TypeScript; all pages are SSR or SSG where appropriate.
• All API routes validate input with Zod; return explicit status codes and structured error messages.
• Auth flows: Clerk front-end integration; verify sessions on server endpoints; never trust client state for authorization decisions.
• Database access via Supabase client with RLS; policy definitions must restrict data by user context.
• AI routing rules in fsm-ai must be deterministic and auditable; log decisions for every assignment.
• Payments: Stripe webhooks must validate signatures and update subscriptions atomically.
• Do not hard-code secrets; use environment variables and secret managers.

Security and Production Rules

• Enable TLS on all endpoints; enforce CSP and secure cookies.
• Audit admin actions; maintain an immutable audit_log table for critical changes.
• Implement input validation, rate limiting, and robust error handling to avoid data leaks.
• Regularly rotate API keys and secret credentials; restrict service roles to minimum permissions.
• Use webhooks securely; verify signatures for Stripe and other external callbacks.

Testing Checklist

• Unit tests for individual services (frontend hooks, backend handlers, AI decision modules).
• Integration tests for API routes with mocked Clerk and Supabase responses.
• End-to-end tests for job creation, assignment, updates, and customer notifications.
• Performance tests for AI routing scalability and Stripe webhook handling under load.
• Security tests for authentication, authorization, and data access controls.

Common Mistakes to Avoid

• Assuming Clerk/session data is trusted on the client; always verify on the server.
• Overexposing Supabase service keys to the frontend; keep them server-side only.
• Neglecting RBAC/RLS policies and letting data bleed across tenants.
• Not validating and normalizing inputs leading to inconsistent data state.
• Skipping monitoring and alerting for AI decision paths and payments flows.

Related implementation resources: AI Agent Use Case for 3PL Providers Using CRM Tracking Tools To Automatically Draft Updates for Delayed High-Value Freight and Designing thin, production-grade API controller routes that delegate logic to separate service layers.

FAQ

• What is this CLAUDE.md Template used for?

  It provides a ready-to-paste Claude Code block and a stack-specific project layout for a Field Service Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, and AI routing.

• Which stack does this template cover?

  Next.js + TypeScript on the frontend, Supabase as the backend, Clerk for identity, Stripe for payments, and an AI orchestrator for job assignment and notes.

• How do I customize AI job routing rules?

  Modify the AI module in apps/fsm-ai to adjust routing heuristics, add business constraints, and tune weights; ensure decisions are auditable.

• What deployment targets are recommended?

  Deploy the Next.js frontend on a hosting platform like Vercel; run backend and AI services in scalable containers or serverless environments; configure Stripe webhooks.

• What are common security pitfalls?

  Avoid exposing secret keys, bypassing server-side auth checks, and skipping RBAC/RLS policies in Supabase.

FAQ (Schema-ready Answers)

Q: What is this CLAUDE.md Template used for?

A: It provides a ready-to-paste Claude Code block and a stack-specific project layout for a Field Service Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, and AI routing.

Q: Which stack does this template cover?

A: Next.js + TypeScript (frontend), Supabase (backend), Clerk (auth), Stripe (payments), and AI routing/orchestration.

Q: How do I customize AI job routing rules?

A: Update apps/fsm-ai with new constraints and ensure decisions are auditable; surface routing decisions to customers and technicians.

Q: What deployment targets are recommended?

A: Frontend on Vercel; backend/AI services on scalable hosts with Stripe webhooks configured.

Q: What are common security pitfalls?

A: Exposing secrets, skipping server-side authorization, and weak RBAC/RLS policies.