Fleet Management SaaS — CLAUDE.md Template (Next.js, TypeScript, Supabase, Clerk, Stripe)

Overview


This CLAUDE.md template describes a complete Fleet Management SaaS stack built with Next.js, TypeScript, Supabase, Clerk, Stripe, AI route optimization, fuel analytics, and driver tracking. The phrase CLAUDE.md template appears here to satisfy search and automation requirements. This page is designed for developers who want a copyable CLAUDE.md block that encodes the stack constraints and implementation rules for Claude Code.


When to Use This CLAUDE.md Template



- When you are building a production-grade fleet SaaS with real-time routing, telematics, and finance flows.

- When you rely on serverless Next.js APIs, Supabase for data and auth, Clerk for user sessions, and Stripe for payments.

- When you want a single canonical CLAUDE.md block that enforces architecture, security, testing, and deployment rules.


Copyable CLAUDE.md Template


Copy this CLAUDE.md block into your repository to bootstrap Claude Code for the stack described above.


# CLAUDE.md
Project Role: Fleet Platform Architect
Architecture rules:
- Use Next.js app directory with TypeScript
- Use Supabase for storage and auth
- Clerk for user authentication and session management
- Stripe for payments and invoices
- AI route optimization for driver routing and fuel efficiency
- Separate services for routeOptimization, fuelAnalytics, and driverTracking
- Prefer serverless API routes and edge-safe computations when possible

File structure rules:
- app/
- components/
- lib/
- services/
- hooks/
- types/
- db/

Authentication rules:
- Clerk handles user signin, signup, and sessions; enforce server-side auth on sensitive API endpoints
- Admin or fleet manager roles required for financial actions

Database rules:
- Supabase with Postgres; enable Row Level Security on all sensitive tables
- Tables: fleets, vehicles, drivers, trips, routes, fuel_logs, permissions
- Use foreign keys to enforce referential integrity

Validation rules:
- Use Zod for all request payload validation
- Validate data shapes both on client and server boundaries

Security rules:
- Do not embed secrets in client code
- Use environment variables for keys and tokens
- Enforce least privilege for service accounts
- Verify Stripe webhooks with signature validation

Testing rules:
- Unit tests for services and utilities
- Integration tests for data flows with Supabase and Stripe
- End-to-end tests for core user journeys (routing, tracking, payments)
- CI should run lint, type checks, and tests on PRs

Deployment rules:
- Deploy on Vercel with automatic previews
- Configure Stripe webhooks and environment variables in production
- Use secret management for credentials

Things Claude must not do:
- Access secret keys from client code
- Bypass Clerk authentication checks
- Expose admin APIs publicly without authorization

Recommended Project Structure


fleet-manager
├─ app
│  ├─ layout.tsx
│  ├─ page.tsx
│  ├─ dashboard
│  │  └─ page.tsx
│  └─ api
│     ├─ auth
│     ├─ stripe
│     └─ route-optimization
├─ components
├─ lib
│  ├─ supabase.ts
│  └─ stripe.ts
├─ services
│  ├─ routeOptimization.ts
│  ├─ fuelAnalytics.ts
│  └─ driverTracking.ts
├─ hooks
└─ types

Core Engineering Principles



- Clarity and correctness over cleverness

- Typed interfaces and strict input validation

- Security by default and least privilege

- Separation of concerns with clean boundaries

- Observability through tracing, metrics, and logging


Code Construction Rules



- Prefer TypeScript with strict mode; no any

- Server-side API routes for business logic; avoid client secrets

- Supabase JS SDK v2 for all DB and auth operations

- Clerk for auth; enforce server-side auth checks

- Do not inline secrets in code; use environment variables

- Do not bypass validation; all inputs must be validated


Security and Production Rules



- Enable Supabase Row Level Security for sensitive tables

- Store all credentials in environment variables; use secret management

- Rotate keys and implement secret rotation policies

- Verify Stripe webhooks with signatures

- Audit logs for critical finance flows


Testing Checklist



- Unit tests for services and utilities

- Integration tests for data flows across Supabase and Stripe

- End-to-end tests for route optimization and driver tracking

- Deployment smoke tests in CI


Common Mistakes to Avoid



- Assuming client code can perform privileged DB operations

- Ignoring data validation at API boundaries

- Disabling CORS or weakening auth checks for convenience



Related implementation resources: AI Agent Use Case for Courier Fleets Using Fuel Consumption Indexes To Identify and Flag Aggressive Driving Habits and Stop AI Agents From Leaking Secrets: Credential Management for AI Workspaces.




FAQ






What is this CLAUDE.md Template for?This CLAUDE.md template encodes Claude Code instructions to implement a complete Fleet Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, AI route optimization, fuel analytics, and driver tracking.
Which technologies does this cover?Next.js, TypeScript, Supabase, Clerk, Stripe, AI route optimization, fuel analytics, driver tracking.
What should Claude do with this template?Follow the instructions to generate a starter CLAUDE.md block that configures architecture, repository layout, and constraints for the stack.
What should Claude avoid?Avoid embedding secrets in client code, bypassing auth, and performing privileged DB operations on the client side.
How is testing organized?Unit tests for utilities, integration tests for data flows, and end-to-end tests for critical user journeys; deploy tests in CI.