CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe Property Management SaaS

Overview

CLAUDE.md template is a copyable instruction block that guides Claude Code to implement a complete Property Management SaaS stack using Next.js, TypeScript, Supabase, Clerk, Stripe, AI maintenance triage, a tenant portal, and rent tracking. This template codifies architecture constraints, file structure, data model considerations, authentication rules, and deployment guardrails, enabling developers to paste a ready-to-run CLAUDE.md into their project.

Direct answer summary: This CLAUDE.md Template encodes architecture, file layout, security, validation, testing, and deployment rules for a production-ready Next.js-based Property Management SaaS with AI triage and payments.

When to Use This CLAUDE.md Template

• Building a complete Property Management SaaS using Next.js, TypeScript, Supabase, Clerk, and Stripe.
• Implementing an AI-driven maintenance triage module that analyzes tickets, suggests actions, and can auto-create tasks with human approval when necessary.
• Creating a tenant portal with secure authentication, onboarding, and real-time rent tracking.
• Defining a repeatable Claude Code workflow with strict architecture, security, and deployment constraints.
• Ensuring production-grade validation, testing, and deployment guidelines are followed.

Copyable CLAUDE.md Template

# CLAUDE.md
Project Role: You are Claude, an AI software architect specialized in building end-to-end SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe, AI maintenance triage, and tenant portals. Your output must be a concrete, copyable CLAUDE.md template that a developer can paste into a CLAUDE.md file to drive Claude Code for this stack. Do not output anything else beyond the template block except for the required surrounding sections in this page.
 
Architecture Rules:
- Use Next.js App Router (app/) with TypeScript. 
- Connect to Supabase as the primary backend; enable Row Level Security (RLS) on all tables; strictly enforce policies for CRUD operations.
- Integrate Clerk for authentication and authorization; define roles: admin, property_manager, tenant.
- Stripe must handle all payment flows (customer creation, subscriptions, one-time payments) via webhooks and secure endpoints.
- Implement an AI maintenance triage model that analyzes tickets, suggests actions, and can auto-create tasks for human agents when appropriate; never modify tenant or property data automatically without approval.
- All API routes must be typed with TypeScript, validated using Zod, and have proper error handling and metrics.

File Structure Rules:
- Use a monorepo layout with apps/web as the Next.js project.
- Place domain-specific code under libs/ (e.g., libs/supabase, libs/ clerk, libs/ stripe, libs/ai, libs/tenant-portal, libs/rent-tracker).
- Do not embed database schema in client code; maintain migrations and policies in a server-bound place (e.g., sql or db-migrations under libs/supabase).
- All UI components live in apps/web/components; keep business logic in libs/.

Authentication Rules:
- Require Clerk session for all sensitive endpoints; enforce role checks on server and client.
- Use short-lived access tokens with refresh tokens; store tokens in httpOnly cookies.

Database Rules:
- Supabase tables: properties, units, tenants, leases, rents, payments, tickets, maintenance_comments, ai_triage, and actions.
- Enable RLS with policies: tenants can read their own rents and tickets; property_managers can manage properties and leases; admins have full access.
- Never expose full tenant data to admins accidentally; restrict by policy.

Validation Rules:
- Use Zod schemas for all API input; reject invalid payloads with clear messages.

Security Rules:
- Do not hard-code secrets; use environment variables and secret management.
- Validate Stripe webhook signatures; verify origin via Clerk tokens where applicable.
- Enforce CSRF protection for state-changing operations.

Testing Rules:
- Unit tests for all domain logic (validation, pricing, AI triage scoring).
- Integration tests for API routes (auth, rents, payments, tickets).
- End-to-end tests for tenant portal flows (login, rent payments, ticket creation).
- CI must run tests on PRs; ensure tests fail on flaky assertions.

Deployment Rules:
- Deploy via Vercel or similar; ensure ENV vars for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET_KEY, STRIPE_WEBHOOK_SECRET, NEXTAUTH_URL, and payment keys are configured.
- Webhook endpoints must be deployed behind a secure route and verified.

Things Claude Must Not Do:
- Do not bypass authentication or authorization checks.
- Do not hard-code secrets or credentials in code blocks.
- Do not perform destructive data migrations without explicit review.
- Do not assume Stripe test keys in production.
- Do not modify tenant data without explicit approval in the UI workflow.

Recommended Project Structure

my-pm-saas/
├── apps/
│   └── web/                 // Next.js 14 app
├── libs/
│   ├── supabase/            // DB schemas, policies, migrations
│   ├── clerk/               // Auth wrappers
│   ├── stripe/              // Payments integration
│   ├── ai/                  // AI maintenance triage helpers
│   ├── tenant-portal/       // Tenant-facing domain
│   └── rent-tracker/        // Rent management domain
├── infra/
│   └── deployments/         // hosting configs, secrets management (secure)
└── README.md

Core Engineering Principles

• Explicit, typed interfaces across the stack to prevent runtime errors.
• Strict separation of UI, business logic, and infrastructure; limits coupling between apps/web and libs/ modules.
• Secure defaults: enforce Supabase RLS, Clerk-based auth, and Stripe webhook verification by default.
• Idempotent operations for payments and maintenance actions; every action is auditable.
• Observability: structured logging and metrics for API and background tasks.

Code Construction Rules

• All API routes must be typed with TypeScript and validated with Zod.
• Do not hard-code secrets; fetch from environment variables and secret managers.
• Do not rely on client-only validation; perform server-side validation for all critical paths.
• Use Supabase Row Level Security with precise policies; never expose data beyond policy.
• Do not mix UI components with business logic; keep libs/ domain code pure.
• Prefer server components for data fetching; keep client components lean.
• Do not reference disallowed libraries for authentication or payments; use Clerk and Stripe official SDKs.

Security and Production Rules

• Enable and enforce Supabase RLS with policies per table; tenants read only their data; managers and admins have broader access per policy.
• Secure all cookies; enable HttpOnly and Secure flags; set SameSite=Lax or strict as appropriate.
• Validate Stripe webhooks with the Stripe signature; store webhook events for auditing.
• Use environment-based feature flags; avoid code-paths that reveal data in non-prod environments.
• Implement observability: structured logs, traces, and error reporting in prod.

Testing Checklist

• Unit tests for domain models, validation schemas, and AI triage scoring logic.
• Integration tests for authentication, rents API, payments, and tickets workflows.
• End-to-end tests for tenant portal flows using Playwright or Cypress.
• CI should run lint, type checks, and test suites on PRs; flaky tests must be stabilized.
• Regression tests for policy changes to ensure RLS policies do not leak data.

Common Mistakes to Avoid

• Assuming client-side validation is sufficient.
• Over-privileging admin access without proper policies.
• Storing secrets in code or committing Stripe keys in repo.
• Ignoring Supabase RLS implications when adding new tables.
• Building without a proper CI/CD workflow or lacking end-to-end tests.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and The Zero-Touch Booking Experience: Agentic Workflows That Drive Loyalty.

FAQ