CLAUDE.md Template: Next.js, TypeScript, Supabase, Clerk, Stripe for Maintenance SaaS

Overview

The CLAUDE.md template provides a comprehensive blueprint to build a Maintenance Management SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and an AI failure-prediction module. It is tailored for developers who want to paste a ready-to-run Claude Code block into a CLAUDE.md file to boot a production-grade system that tracks asset history, supports work orders, and includes AI-driven operational insights.



When to Use This CLAUDE.md Template



  - Launching a production-ready maintenance SaaS with asset histories and work orders.

  - Integrating user authentication (Clerk) and payments (Stripe) in a cohesive stack.

  - Implementing AI-driven failure prediction to optimize maintenance scheduling and asset uptime.

  - Onboarding new engineers with a dense, copyable Claude Code blueprint.



Copyable CLAUDE.md Template


Use this exact CLAUDE.md block to bootstrap the project. It includes project role, architecture rules, file structure guidance, and hard rules to ensure reliability and security.


# CLAUDE.md
Project Role: You are Claude Code, building a complete Maintenance Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, AI failure prediction, work orders, and asset history.

Architecture Rules:
- Use Next.js App Router with TypeScript; server components where beneficial; separate server/client boundaries clearly.
- Persist data in Supabase; manage authentication via Clerk; handle payments with Stripe; integrate AI failure prediction for assets.
- Design with modular, testable services; avoid monolithic code paths; expose clean, typed APIs.
- Prefer API Routes or Route Handlers for server logic; keep business logic in services/ domain layers.

File Structure Rules:
- Root: src/ with app/ for UI routes; lib/ for shared clients; services/ for business logic; models/ for domain types; components/ for UI.
- Domain grouping: assets/, work-orders/, asset-history/, ai-predictions/ under src/
- UI components under src/components/; API wrappers under src/lib/; integration logic under src/services/

Authentication Rules:
- Clerk for authentication; all protected routes require an active session; never expose private keys on the client.
- Use role-based access: admin can manage payments and tenants; user can interact with assets/work orders.
- Use server-side session verification for critical actions.

Database Rules:
- Supabase tables: assets(id PK, name, location, asset_code, status, last_serviced, etc.), work_orders(id PK, asset_id, status, priority, assigned_to, created_at), asset_history(id PK, asset_id, timestamp, event, notes), failure_predictions(id PK, asset_id, score, created_at).
- Implement Row Level Security with tenant isolation and role checks; deny privileged actions from unauthenticated users.
- Create foreign keys assets.id -> work_orders.asset_id; assets.id -> asset_history.asset_id; asset_id in failure_predictions references assets.

Validation Rules:
- Enforce strong types in TypeScript; validate inputs in API routes and UI forms; never trust client input.
- Validate IDs, foreign keys, and status values against enumerations.
- Normalize and sanitize strings; guard against XSS and injection.

Security Rules:
- Store secrets in environment variables; do not commit keys; rotate secrets regularly.
- Validate Stripe webhooks with signature; verify Clerk JWTs on protected endpoints.
- Enable CSRF protection on write endpoints; use HTTPS-only cookies and SameSite=Lax/Strict.

Testing Rules:
- Unit tests for validation logic, data transformation, and AI prediction scoring.
- Integration tests for auth flows, API endpoints, and payment flows.
- End-to-end tests for key user journeys: create work order, update asset history, and resolve maintenance tasks.
- Include performance tests for AI prediction path under representative loads.

Deployment Rules:
- Use environment variables for all secrets (SUPABASE_URL, SUPABASE_KEY, CLERK_API_TOKEN, STRIPE_WEBHOOK_SECRET).
- Deploy with a modern hosting platform (e.g., Vercel) and enable edge caching where appropriate.
- Configure Stripe webhooks and secure endpoints; monitor deploy health and error budgets.

Things Claude Must Not Do:
- Do not bypass authentication or expose private keys in the client bundle.
- Do not perform direct DB writes without validation; do not assume trusted client input.
- Do not disable security policies or bypass RLS rules in production.


Recommended Project Structure


maintenance-management/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── asset-history/
│   │   └── page.tsx
│   └── work-orders/
│       └── page.tsx
├── components/
├── lib/
│   ├── supabaseClient.ts
│   │   └── index.ts
│   ├── clerkClient.ts
│   └── stripeClient.ts
├── models/
│   ├── asset.ts
│   ├── workOrder.ts
│   └── history.ts
├── services/
│   ├── aiPrediction.ts
│   └── payment.ts
├── public/
├── styles/
├── types/
└── utils/


Core Engineering Principles



  - Explicit types and contracts for all public APIs and modules.

  - Tenant-aware data access with strict isolation (RLS).

  - Clear separation of concerns between UI, API, and business logic.

  - Fail-fast design for critical paths like auth, payments, and AI predictions.

  - Automated tests are a first-class requirement for every feature.



Code Construction Rules



  - Use TypeScript everywhere; prefer interfaces/types over any.

  - Server components fetch data; client components render with reduced props and clear boundaries.

  - Validate inputs on both client and server; adopt schema validation for API contracts.

  - Keep business logic in services/ domain modules; UI should be presentation-only.

  - Write tests for auth, payments, AI predictions, and maintenance workflows.



Security and Production Rules



  - Enable Supabase RLS for tenant isolation; assign roles carefully.

  - Store secrets in environment variables; never commit secrets to source control.

  - Validate Stripe webhooks with signatures; secure Clerk sessions on protected routes.

  - Apply CSRF protection and enforce HTTPS; audit trails for critical actions.

  - Monitor logs, metrics, and error budgets; rotate credentials periodically.



Testing Checklist



  - Unit tests for validators and utilities.

  - Integration tests for API routes (auth, assets, work orders, AI predictions).

  - End-to-end tests for core flows (create work order, update asset history, complete maintenance).

  - Performance tests for AI-prediction components under simulated load.

  - Deployment smoke tests to verify environment parity after deploy.



Common Mistakes to Avoid



  - Skipping server-side validation and sanitization.

  - Misconfiguring Stripe webhooks or Clerk auth roles.

  - Neglecting tenant isolation in database access.

  - Hard-coding secrets or diverging environment configurations.



Related implementation resources: AI Agent Use Case for Telecom Infrastructure SMEs Using Battery Cell Health Telemetry To Schedule Generator Cell Swaps and Managing runtime hydration layers to avoid client-side compilation conflicts in production.





FAQ



  - What is a CLAUDE.md template for this stack? A copyable Claude Code blueprint that prescribes how to implement a maintenance management SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and AI-driven failure prediction for assets and work orders.

  - Which components are covered by this template? Next.js app with TypeScript, Supabase database, Clerk authentication, Stripe payments, AI failure prediction module, work orders, and asset history tracking.

  - How should I structure the project? Follow the Recommended Project Structure block. It provides a stack-specific directory tree and file layout.

  - Is this template production-ready? Yes, it defines concrete rules for architecture, security, validation, testing, and deployment suitable for a real SaaS.

  - What should I not do when implementing this stack? Do not bypass authentication, expose secret keys, skip server-side validation, or disable data security policies.