CLAUDE.md Template: Facility Management SaaS (Next.js, TS, Supabase, Clerk, Stripe)

Overview

CLAUDE.md template for building a complete Facility Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, AI ticket routing, asset tracking, and maintenance analytics. This page includes a copyable CLAUDE.md block you can paste into Claude Code to bootstrap the stack end-to-end.

Direct answer: This CLAUDE.md Template provides a production-ready blueprint to implement a Next.js + TS frontend, with Supabase as the backend, Clerk for authentication, Stripe for payments, and Claude Code-driven automation for AI routing, asset tracking, and analytics in a Facility Management SaaS.

When to Use This CLAUDE.md Template

• When you need a fast-start blueprint to spin up a complete SaaS with authentication, payments, and data-driven maintenance analytics.
• When you want a copyable CLAUDE.md template that enforces architecture rules and security constraints for this stack.
• When you need a consistent project structure across teams to support AI-driven ticket routing and asset management.
• When you require production-ready validation, testing, and deployment rules embedded in the template.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: Lead Frontend Engineer, Cloud-First Architect, and Claude Code Integrator for a Next.js + TS + Supabase + Clerk + Stripe stack focused on AI ticket routing, asset tracking, and maintenance analytics.

Architecture Rules:
- Build a serverless-first Next.js app using App Router with TypeScript. Use Supabase as the primary database layer and Clerk for authentication. Implement Stripe for subscription and pay-per-use flows. Claude Code will orchestrate AI ticket routing, asset tagging, and maintenance analytics.
- All data access must pass through typed APIs; never call database directly from UI components.
- Use a single source of truth: assets, tickets, maintenance events stored in Supabase with strict schemas.
- Separate concerns: frontend UI, API layer, and background jobs must be isolated and testable.
- Follow a strict identity and access policy with Clerk Roles; enforce least privilege for service accounts.
- Deploy via GitHub Actions; environment variables must be secured in Secrets; no plaintext keys in repo.
- Claude must not mutate client-side state in React components except through explicit actions.
- All external API calls must be validated, rate-limited, and monitored; handle retries with exponential backoff.

File Structure Rules:
- Put frontend pages under src/app; backend services under src/lib and src/services; data models under src/models.
- Use a modular component library under src/components; keep pages small and composition-driven.
- Use a dedicated Supabase client in src/lib/supabase.ts; a Clerk client in src/lib/clerk.ts; and Stripe client in src/lib/stripe.ts.
- Store environment-specific config in .env.* files; never hardcode secrets.
- Tests live under __tests__ directories parallel to their code.

Authentication Rules:
- Use Clerk for authentication and authorization; support email/password and social providers.
- Protect API routes with getServerSession-like guards; check user roles on every sensitive operation.
- Anonymous access is disallowed for any maintenance or billing endpoints.

Database Rules:
- Supabase database with schemas for assets (assets), tickets (tickets), maintenanceEvents (maintenance_events), users (profiles).
- Use Row Level Security (RLS) with policies per table; apply at read and write levels based on roles.
- All IDs must be UUIDv4; created_at/updated_at timestamps must be automatic.

Validation Rules:
- Use runtime schema validation (e.g., Zod) on all inputs; API layer must validate request bodies and query params.
- Backend must reject invalid IDs, dates, or amounts; return clear error messages.

Security Rules:
- Always validate inputs; escape HTML in UI; avoid XSS; enable CSRF protection where relevant.
- Secrets must be stored securely; rotate keys periodically; monitor for suspicious activity.
- Webhooks from Stripe must be verified with signature; use pinned SSL and enforce secure cookies.

Testing Rules:
- Unit tests for UI components and hooks; integration tests for API routes and database adapters; end-to-end tests for critical flows (sign-in, create ticket, assign, resolve).
- Use mocks for external services (Stripe, Clerk) in unit tests; use a dedicated test database with sandboxed data.
- CI must run tests on push and PRs; require all tests to pass before merge.

Deployment Rules:
- Deploy to Vercel (or preferred platform) with preview deployments; separate production and staging environments.
- Use environment variables: SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_FRONTEND_API, STRIPE_SECRET_KEY, WEBHOOK_SECRET.
- Ensure Stripe webhooks are configured and tested; deploy with proper domains and SSL.

Things Claude Must Not Do:
- Do not bypass Clerk authentication; do not access Surfer or other unrelated services.
- Do not expose secrets in the frontend; never log sensitive user data.
- Do not bypass Supabase security policies; do not assume raw table access from client.
- Do not use non-production credentials in production; do not skip tests or deployment checks.

Recommended Project Structure

src/
  app/
    authentication/                 # Clerk integration (config, hooks, pages)
    assets/                          # Asset tracking UI
    tickets/                         # AI ticket routing and ticket workflows
    maintenance-analytics/           # Analytics dashboards and reports
    dashboard/
  components/
  lib/
    supabase.ts
    clerk.ts
    stripe.ts
  models/
  services/
  hooks/
  utils/
  public/

Core Engineering Principles

• TypeScript-first: define strict interfaces and runtime schemas; avoid any.
• Separation of concerns: one module per concern; testable boundaries.
• Idempotence: operations should be idempotent where possible.
• Observability: structured logs, metrics, and tracing for critical paths.
• Security by default: enforce least privilege, input validation, and secure storage.
• Accessibility and performance: accessible UI, optimized bundles, and SSR where appropriate.

Code Construction Rules

• Use Next.js App Router with TypeScript for all routes; API routes must be in src/app/api.
• Frontend components must be pure and free of side effects during render; use hooks for data fetching.
• API layer must expose typed endpoints; responses must have consistent shape and status codes.
• Use Clerk for authentication; any user data access must be role-checked.
• Supabase client must be initialized once; reuse across modules; avoid multiple instances.
• Server Components should fetch data; Client Components manage interactive state.
• Validation via runtime schemas; type-safe data handling from API to UI.
• Do not use direct DOM manipulation in server components; avoid window/document in SSR.
• Deployment should use environment-based config; secrets must not be checked in.
• Do not vendor large libraries unless needed; prefer lightweight packages with solid maintenance.
• Do not implement business logic in UI components; keep logic in API/services.

Security and Production Rules

• Enforce CSRF protection for API routes; use signed cookies for sessions.
• Validate Stripe webhooks with signature and replay protection.
• Enforce strict CORS policies for public APIs.
• Rotate secrets; monitor for exposure; implement audit logs for critical actions.
• Do not log PII or secrets in logs; mask sensitive fields in responses.

Testing Checklist

• Unit tests for components and hooks; API route tests with mocked database.
• Integration tests for core flows (auth, ticket routing, asset updates).
• End-to-end tests for sign-in, asset creation, and ticket assignment.
• CI should run tests on PRs; require 0 test failures.

Common Mistakes to Avoid

• Overusing server components for dynamic UI.
• Skipping security reviews; exposing secrets in frontend.
• Neglecting to test Stripe webhooks with signature verification.
• Ignoring data privacy in asset tracking (PII handling).

Related implementation resources: AI Agent Use Case for Facility Management Firms Using Maintenance Tickets to Identify Recurring Building Issues and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ

• Q: What is a CLAUDE.md template?
  A: A copyable blueprint for Claude Code that instructs how to implement a full stack using a specified tech stack.
• Q: Which stack does this template cover?
  A: Next.js, TypeScript, Supabase, Clerk, Stripe, AI ticket routing, asset tracking, and maintenance analytics.
• Q: How do I customize for a different frontend or backend?
  A: Update the project role, adapt APIs, and swap back-end services (e.g., different auth or database) in the CLAUDE.md block and project structure, while preserving the architecture rules.
• Q: Can I use this template for production deployments?
  A: Yes, but follow the Deployment Rules and Security guidelines outlined in the CLAUDE.md block and ensure all tests pass in CI.
• Q: How do I test the AI ticket routing workflow?
  A: Use unit tests for routing logic, integration tests for routing endpoints, and end-to-end tests on the full ticket lifecycle with mocked AI outputs where appropriate.