CLAUDE.md Template: Real Estate CRM with Next.js, TypeScript, Supabase, Clerk, Stripe

Overview

A CLAUDE.md template for building a complete Real Estate CRM using Next.js, TypeScript, Supabase, Clerk, Stripe, AI property matching, lead scoring, and listing pages. This page is a copyable CLAUDE.md template you can paste into a CLAUDE.md file to bootstrap a production-ready stack.

Direct answer: This CLAUDE.md Template provides architecture guidance, file structure, and Claude Code instructions tailored to a modern Real Estate CRM stack, ensuring a secure, scalable, and testable implementation.

When to Use This CLAUDE.md Template

• You need a copyable Claude Code block that covers the full stack: Next.js frontend, TypeScript, Supabase as the backend, Clerk for auth, Stripe for payments, plus AI-driven property matching and lead scoring.
• You want stack-specific architecture rules, file structure, and deployment guidance in a single CLAUDE.md template.
• You require strict security, validation, and testing rules to ship a production-ready Real Estate CRM.

Copyable CLAUDE.md Template

# CLAUDE.md
Project Role: You are Claude Code, assisting in building a production-grade Real Estate CRM with Next.js (App Router), TypeScript, Supabase, Clerk, Stripe, AI property matching, and lead scoring. Your job is to provide clear, executable Claude Code instructions and guardrails for this stack.

Architecture Rules:
- Monorepo structure with a dedicated frontend (Next.js) and backend (Supabase) layer; share types via a common tsconfig-paths setup.
- Data flows: Client → API Routes → Supabase (PostgreSQL). Stripe webhooks must be verified. AI scoring uses server-side evaluation.
- Prefer server components for data-heavy pages; hydrate with client components where interactivity is needed.
- Use edge functions for latency-sensitive rules (auth, webhooks, property matching) and server functions for DB access.
- All secrets must be stored in environment variables; never commit secrets.
- Use REST + RPC endpoints: RPCs for complex queries; REST for resource operations.
- Implement Role-Based Access Control (RBAC) with Clerk; enforce Row-Level Security (RLS) on Supabase tables.
- Use TypeScript types across the stack; avoid any and enforce strictNullChecks.
- Logging, metrics, and tracing must be configured for all layers (Frontend, API, DB).

File Structure Rules:
- Keep a clear frontend/backend boundary: apps/web for Next.js, supabase/ for database and edge functions, packages/shared for shared types.
- All API endpoints under apps/web/src/pages/api or app/api (Next.js 13+ App Router) for consistency.
- Use a shared lib/types directory for common TypeScript interfaces (Property, Lead, User, Listing, Payment, Score).
- Include infra/ for deployment tooling, environment samples (.env.example), and GH workflows.
- Do not mix frontend components with backend business logic in the same file.

Authentication Rules:
- Clerk handles sign-in/sign-up and user sessions; front end should verify session on each protected page using Clerk hooks.
- Ensure only authenticated users can mutate sensitive data; enforce on API routes and server actions.
- Do not expose personal data on the client; fetch sensitive fields on server and pass sanitized results.

Database Rules:
- Supabase PostgreSQL with tables: properties, listings, leads, users, scores, transactions, images.
- Enforce Row-Level Security (RLS) policies to restrict reads/writes based on user role and ownership.
- Use foreign keys for data integrity; create materialized views for AI property matching results.
- For AI results, store a reference to the source model and version.

Validation Rules:
- Validate all incoming data on API routes and server actions; use Zod schemas to shape data.
- Ensure property features are enumerated and mapped to a canonical schema.
- Validate Stripe webhook signatures; reject invalid webhooks.

Security Rules:
- Do not store plaintext API keys in client code.
- Enable HTTPS; configure CORS strictly for known frontends.
- Use CSRF protection on mutating endpoints.
- Audit admin actions; enable database-level audit triggers.

Testing Rules:
- Unit tests for UI components and utils; integration tests for API routes and Supabase RPCs.
- End-to-end tests covering login, property search, lead capture, and payments flow.
- Run tests in CI and post artifacts on failure.

Deployment Rules:
- Deploy frontend to Vercel or similar; deploy Supabase migrations and edge functions alongside.
- Environment variables: NEXT_PUBLIC_* for public data; SECRET_* for server secrets.
- Ensure Stripe webhooks endpoint is deployed and tested with live/test keys.

Things Claude Must Not Do:
- Do not bypass Clerk RBAC or rely on client-side authorization checks alone.
- Do not hard-code secrets or API keys in CLAUDE.md or code blocks.
- Do not assume Prisma in the stack if not used; use Supabase for DB interactions.
- Do not create overly permissive database permissions; enforce least privilege.

Recommended Project Structure

real-estate-crm/
├── apps/
│   └── web/                 # Next.js frontend (App Router)
│       ├── public/
│       ├── src/
│       │   ├── app/
│       │   ├── components/
│       │   ├── features/
│       │   ├── hooks/
│       │   └── styles/
│       ├── next.config.js
│       └── tsconfig.json
├── supabase/
│   ├── migrations/
│   ├── functions/
│   └── .env
├── packages/
│   └── shared/               # TS types, utilities shared between frontend/backend
├── infra/
│   ├── scripts/
│   └── workflows/
└── .env.example

Core Engineering Principles

• Strong typing and explicit contracts across frontend, API, and DB.
• Security by default: RBAC, RLS, and validated inputs at every boundary.
• Modular architecture with clear separation of concerns.
• Idempotent operations for APIs and idempotent deployments.
• Observability: structured logs, metrics, and tracing.
• Test-driven emphasis: unit, integration, and end-to-end tests.

Code Construction Rules

• Use Next.js App Router with TypeScript; organize by feature modules under apps/web/src/app.
• Prefer server components for data fetching; client components for interactivity only.
• Supabase as the primary backend: ensure RLS, foreign keys, and secure RPCs.
• Clerk for authentication; enforce protected routes and proper session handling.
• Stripe for payments; verify webhooks and store webhook events safely.
• AI property matching: implement a server-side scoring function that consumes property features and user preferences; cache results when possible.
• Validation with a typed schema (e.g., Zod) on all inputs; fail fast on invalid data.
• Do not hard-code secrets; centralize in environment variables and secret managers.
• Do not bypass server-side authorization checks with client-side hints.

Security and Production Rules

• Enforce Clerk RBAC and Supabase RLS on all sensitive resources.
• Verify all Stripe webhooks with signatures; store only minimal data in client-visible contexts.
• Use CSRF protection for mutating endpoints and server actions.
• Use encrypted secrets and rotate keys periodically.
• Audit admin changes and maintain immutable logs where possible.

Testing Checklist

• Unit tests for UI components and utilities.
• API integration tests for all endpoints (auth, properties, leads, payments).
• End-to-end tests covering login, search, lead capture, AI matching, and checkout.
• Performance checks for AI scoring and listing pages.
• Deployment validation: environment variables, migrations, and webhooks wiring.

Common Mistakes to Avoid

• Ignoring Supabase Row-Level Security policies (RLS) on sensitive tables.
• Exposing service keys or secret tokens in frontend code or CLAUDE.md blocks.
• Under-predicting data validation leading to inconsistent data shapes.
• Over-fetching data on listing pages causing slowness.
• Skipping Stripe webhook verification or misconfiguring event handling.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Production-grade billing logic governed by project rules.

FAQ