CLAUDE.md Template for Construction Project SaaS (Next.js, TypeScript, Supabase, Clerk, Stripe, AI Delay Prediction, Documents, Budgets, Site Reports)

Overview

The CLAUDE.md template is a practical Claude Code blueprint for building a complete Construction Project SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI delay prediction, documents, budgets, and site reports. This page is a copyable CLAUDE.md template designed for developers implementing the stack in production. Direct answer: it provides concrete architecture, auth, data, and deployment guidance tailored to a Next.js + TS + Supabase + Clerk + Stripe workflow with documents and site reporting features.

When to Use This CLAUDE.md Template

• Starting a new Construction Project SaaS with the given stack (Next.js, TS, Supabase, Clerk, Stripe).
• Standardizing Claude Code practices for architecture, data modeling, and auth flows.
• Ensuring security, production-readiness, and observable deployments from day one.
• Providing a concrete blueprint for teams to collaborate on feature parity across docs, budgets, and site reports.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code, a software architect AI that writes production-ready CLAUDE.md templates for the Construction Project SaaS stack (Next.js, TypeScript, Supabase, Clerk, Stripe).

Architecture rules:
- Use a clean layered architecture: UI (Next.js) + API layer (Next.js API routes) + data layer (Supabase) + auth (Clerk) + payments (Stripe).
- Favor server components for data-heavy pages; isolate client components via hooks and context.
- All API calls must be strictly typed and validated.
- Prefer edge functions for latency-sensitive logic; use server components for SSR where possible.
- Do not rely on client-side secrets; use environment variables and secure server contexts.

File structure rules:
- Keep a single source of truth for domain models in /src/types and /src/lib.
- Put pages under /apps/web/src/app if using App Router; place API routes under /apps/web/src/pages/api or /src/app/api if using app router.
- Create feature folders: /documents, /budgets, /reports with their own components, hooks, and services.

Authentication rules:
- Clerk must be the sole authentication provider; enforce email/password or OAuth flows.
- Ensure server-side session validation for restricted endpoints.
- Implement role-based access: admin, project-manager, field-traveler.

Database rules:
- Use Supabase Postgres with RLS enabled; define policies for documents, budgets, and site reports by tenant and user role.
- Enforce data isolation by projectId and userId in every table.
- Store immutable audit trails for critical actions.

Validation rules:
- Validate all inputs with a schema (eg. Zod) before interacting with the database.
- Normalize and sanitize strings to prevent injection.
- Validate document uploads with size limits and allowed mime-types.

Security rules:
- Never embed secret keys in client code.
- Validate webhook signatures for Stripe and Clerk on the server.
- Use CSRF protection and rate limiting on sensitive endpoints.

Testing rules:
- Write unit tests for all utility functions and types.
- Write integration tests for auth flows, Stripe webhooks, and Supabase data access (mocked in unit tests).
- Include end-to-end tests for core user journeys: sign-in, create project, add documents, generate site reports, and billing flow.

Deployment rules:
- Use Vercel or a similar hosting provider; configure environment variables per environment.
- Set up Stripe webhooks in production and verify signature on receipt events.
- Enable automatic deployments on main; perform a canary test on previews.

Things Claude must not do:
- Do not hard-code production secrets; avoid any insecure shortcuts.
- Do not bypass Supabase RLS; never fetch data outside defined policies.
- Do not assume clients can perform server-only operations.

Recommended Project Structure

construction-saas/
  apps/
    web/
      src/
        app/
          layout.tsx
          page.tsx
          dashboard/
            page.tsx
          projects/
            [projectId]/
              page.tsx
          documents/
            page.tsx
          budgets/
            page.tsx
          reports/
            page.tsx
        components/
          common/
          ui/
        lib/
          api.ts
          supabase.ts
        services/
          billing.ts
          aiDelay.ts
        hooks/
          useAuth.ts
        styles/
          globals.css
        types/
          index.d.ts
      package.json
  docs/
    templates/
      claude-md/
        construction-saas-nextjs-claude-md-template.md
  infra/
    supabase/
    clerk/
    stripe/
  scripts/
    deploy.sh

Core Engineering Principles

• Single source of truth for domain models and UI behavior.
• Strong separation of concerns between UI, business logic, and data access.
• Explicit, typed interfaces for all API boundaries.
• Security-by-default with proper auth and data access policies (RBAC, RLS).
• Observability through structured logging, metrics, and tracing.

Code Construction Rules

• Type everything; prefer TypeScript interfaces and generics for API surfaces.
• Validate inputs with a schema library (eg. Zod) on both client and server sides.
• Keep API surface small and well-typed; avoid serverless function bloat.
• Use Supabase client with role-based access control; never trust client data for critical actions.
• Implement robust error handling with user-friendly messages and error codes.
• Document all public APIs and data contracts in a central place.
• Do not hard-code secrets in code; use environment variables and secret managers.

Security and Production Rules

• Enable Supabase RLS and define fine-grained policies per table.
• Require Clerk session validation for protected routes; enforce role checks server-side.
• Validate Stripe webhooks on the server; verify signatures.
• Enforce CSRF protection for state-changing requests; implement rate limiting.
• Keep secret keys in a secure vault and rotate credentials regularly.

Testing Checklist

• Unit tests for utilities, types, and domain logic.
• Integration tests for auth, database access, and Stripe webhooks.
• Contract tests for API endpoints to ensure data contracts remain stable.
• End-to-end tests of critical user journeys: sign-in, project creation, document upload, budget update, and report generation.
• Deployment smoke tests and canary validations on preview environments.

Common Mistakes to Avoid

• Assuming client-side validation is sufficient; always validate on the server.
• Relying on insecure storage of secrets in the client bundle.
• Neglecting Supabase RLS policies; data leaks can occur without proper policies.
• Overcomplicating the architecture with unused services or libraries.

Related implementation resources: AI Use Case for Expense Management Startups Using Slack To Let Employees Submit Expense Claims Via Chat Message and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ