CLAUDE.md Template: Freight Broker SaaS with Next.js, TS, Supabase, Clerk, Stripe

Overview

Direct answer: This CLAUDE.md template provides a turnkey blueprint to build a Freight Broker SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI rate intelligence, with end-to-end quote management and shipment tracking.

What it is: A copyable CLAUDE.md template that codifies architecture, file layout, and Claude Code instructions to implement a complete freight brokerage platform. Stack: Next.js with App Router, TypeScript, Supabase (Postgres), Clerk authentication, Stripe payments, AI rate intelligence, quote management, and shipment tracking modules.

When to Use This CLAUDE.md Template

• Bootstrapping a Freight Broker SaaS that handles rate shopping, quotes, and shipment tracking.
• Standardizing CLAUDE Code across multi-service monorepos for a freight workflow.
• Creating a reproducible starter for onboarding new engineers and documenting decisions for operations.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude Code. Your task is to implement a full Freight Broker SaaS stack using Next.js, TypeScript, Supabase, Clerk, Stripe, AI rate intelligence, quote management, and shipment tracking.

Architecture rules
- Use Next.js App Router with TypeScript.
- Supabase Postgres as the primary data store; enable Row Level Security with per-table policies.
- Clerk for authentication; define roles: admin, broker, carrier, customer.
- Stripe for payments; validate webhook signatures; store customer subscriptions and charges.
- AI rate intelligence module integrated via a dedicated service; cache results per carrier, route, and rate request.
- Separate concerns: web app, API layer, and background jobs.
- All secrets must live in environment variables; never commit secrets.
- Use server components where possible; fetch data with server actions; keep client payloads small.

File structure rules
- apps/web as Next.js frontend; packages/db for DB client; packages/ai for AI modules; packages/quotes for quote lifecycle; packages/shipments for tracking; packages/payments for Stripe integration.
- Use .env.local.example for template values; never commit .env files.
- Strict TypeScript types; export types from libs for reuse.
- Use simple, explicit file naming; align with domains: quotes, shipments, rates, users, payments.

Authentication rules
- Clerk handles signup, login, and session management.
- Implement role-based access: brokers can create quotes; customers view quotes; admins manage users.
- Protect server actions with auth checks; never trust client-side data.

Database rules
- Supabase Postgres; tables: users, clients, quotes, shipments, rates, payments, audit_logs.
- Enable Row Level Security for quotes, shipments, payments; create policies to enforce owner and role checks.
- Use foreign keys; ensure referential integrity; audit trails for changes.

Validation rules
- Use Zod for runtime validation on all API boundaries.
- Validate incoming payloads on both server and edge layers.
- Normalize inputs (trim strings, enforce types).

Security rules
- Do not log secrets; never echo API keys in responses.
- Validate Stripe webhooks with signatures; verify Clerk sessions on protected routes.
- Use CSRF protection for state-changing actions where applicable.

Testing rules
- Unit tests for utility functions and validators.
- Integration tests for auth flows, quote lifecycle, and shipment status updates.
- End-to-end tests for user journeys (seller/broker creates quote, track shipment, process payment).
- CI tests must run on PRs; include lint and type checks.

Deployment rules
- Deploy to Vercel or equivalent; configure environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_API_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET.
- Set up Stripe webhook endpoint and test via Stripe CLI.
- Enable monitoring (error tracking, logging) and performance budgets.

Things Claude must not do
- Do not bypass Clerk auth or exposure of secret keys.
- Do not implement business logic that bypasses rate limits or order validation.
- Do not hardcode production credentials.
- Do not rely on client-side only validation for security critical paths.

Recommended Project Structure

/
apps/web/
  app/
    layout.tsx
    page.tsx
    error.tsx
  components/
  hooks/
  lib/
  styles/

packages/db/
  index.ts
  dbClient.ts
  migrations/

packages/ai/
  rate_intelligence/

packages/quotes/
  src/

packages/shipments/
  src/

packages/payments/
  stripe.ts
  webhooks.ts

scripts/
  deploy.sh
  test.sh

Core Engineering Principles

• Security by default: enforce RBAC, input validation, and secret management from day one.
• Single source of truth: centralize domain models and data access layers.
• Clear separation of concerns: UI, API, and background jobs are distinct modules.
• Declarative data contracts: use TypeScript types and Zod schemas for runtime validation.
• Observability: structured logging, tracing for API calls, and error reporting.

Code Construction Rules

• Use TypeScript end-to-end; define domain types in packages/ toward reuse.
• Next.js App Router with server components; minimize client-side JavaScript.
• Supabase client usage on server side; protect API routes with Clerk sessions.
• Stripe integration with webhooks; verify signatures and store customer data.
• AI rate intelligence module as a separate service; cache results and invalidate on updates.
• All API inputs validated with Zod; errors normalized and returned with actionable messages.
• Do not hardcode secrets; use environment variables and secret management.
• Follow a clean coding style; add unit tests alongside code changes.

Security and Production Rules

• Enable Row Level Security on all critical tables in Supabase; enforce owner and role checks.
• Authenticate all protected routes with Clerk; never render sensitive data to unauthenticated users.
• Validate Stripe webhook payloads; store webhook events securely.
• Regularly rotate API keys; monitor for suspicious activity.

Testing Checklist

• Unit tests for validators, helpers, and AI modules.
• Integration tests for auth, quote lifecycle, shipment tracking, and payments.
• End-to-end tests for complete user journeys (broker creates quote, tracks shipment, processes payment).
• CI pipelines to run lint, type checks, unit tests, and integration tests on PRs.
• Performance checks for rate intelligence queries and data fetch paths.

Common Mistakes to Avoid

• Assuming client-side validation is sufficient for security.
• Ignoring RL policies when designing database schemas.
• Storing secrets in repository or frontend code.
• Coupling business logic too tightly to UI components.

Related implementation resources: AI Agent Use Case for Third-Party Logistics (3PL) Firms Using Shipping Historicals To Match Freight Profiles with Budget Carriers and Strategies for connection string pooling across distributed serverless zones.

FAQ

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

A1: It provides a copyable CLAUDE.md blueprint to scaffold a Freight Broker SaaS with Next.js, TS, Supabase, Clerk, Stripe, AI rate intelligence, quotes, and tracking.

Q2: Which stack does it cover?

A2: Next.js App Router, TypeScript, Supabase Postgres, Clerk auth, Stripe payments, AI rate intelligence, and modules for quotes and shipments.

Q3: How do I customize for my freight domain?

A3: Modify the CLAUDE.md code block and adjust architecture rules, file structure, and policies to fit your data model and workflow.

Q4: How do I test the scaffold?

A4: Run unit tests for utilities, integration tests for API routes, and end-to-end tests for user journeys using your preferred tooling.

Q5: Where should I deploy this template?

A5: Deploy to Vercel or your platform; configure environment variables for Supabase, Clerk, and Stripe; set up Stripe webhooks.