CLAUDE.md Template: Clinic Management SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe

Overview

Direct answer: This CLAUDE.md template provides a complete blueprint for building a Clinic Management SaaS stack using Next.js (App Router), TypeScript, Supabase for auth and database, Clerk for UI authentication, Stripe for billing, AI-powered appointment notes, a patient portal, and integrated billing workflows. It includes a copyable CLAUDE.md block, stack-specific architectural guidance, a recommended project structure, security and testing rules, and a concrete implementation roadmap that you can paste into a CLAUDE.md file in Claude Code.

The template targets a production-ready SaaS with end-to-end data flows, role-based access, and secure deployment considerations tailored to a multi-tenant clinic ecosystem.

When to Use This CLAUDE.md Template

• You are building a multi-tenant Clinic Management SaaS with user-facing patient portal, appointment scheduling, notes, and billing.
• You want a single, copyable CLAUDE.md template to guide architecture, file structure, and security for Next.js + TypeScript + Supabase + Clerk + Stripe.
• You require strict RBAC, Stripe webhooks, and AI-assisted notes integrated into patient encounters.
• You need a production-ready blueprint that Claude Code can execute with minimal hand-typing and consistent patterns across modules.

Copyable CLAUDE.md Template

# CLAUDE.md

## Project role
You are Claude Code. Your job is to implement a complete Clinic Management SaaS stack using:
- Frontend: Next.js (App Router) + TypeScript
- Auth: Clerk for UI flows, with user roles synced to Supabase RBAC
- Database: Supabase (PostgreSQL) with Row-Level Security (RLS)
- Payments: Stripe for subscriptions and billing
- AI notes: AI-generated appointment notes during or after patient encounters
- Portal: Patient portal with appointment access and billing history
- Deployment: Vercel-ready configuration with secure env handling

## Architecture rules
1) Use a monorepo pattern under apps/ and packages/ while staying strictly within the Next.js ecosystem.
2) Prefer server components for data-heavy UI; isolate business logic into lib/services.
3) All data access flows must route through server actions or API routes with proper authentication checks.
4) Use Supabase for auth tokens and database; Clerk handles the UI authentication flow and sessions; sync user metadata to Supabase to enable RBAC.
5) Validate all input on the server; serialize data in a predictable shape for the client.
6) Implement AI notes using a secure API call (no client-side secrets).
7) Do not expose API keys or secrets to the client.

## File structure rules
- apps/web/        - Next.js app with app/ directory and pages under app/
- apps/web/app/    - Router and UI; pages/components under this path
- lib/              - Shared utilities (auth, api wrappers, types)
- lib/db/           - Supabase client initialization and server helpers
- lib/ai/           - AI-note generation utilities (server-side only)
- components/       - Reusable UI primitives
- models/           - TypeScript interfaces for core entities (Patient, Appointment, Note, Invoice, Payment)
- db/               - Supabase SQL schema and migration artifacts
- scripts/          - Deployment and migration helpers
- env.example/      - Template environment variables for local development

## Authentication rules
1) Clerk manages sign-in, sign-up, and session flows; All UI routes should require a Clerk session.
2) Sync Clerk user metadata (roles: patient, admin, clinician) into Supabase to enforce RBAC.
3) Server routes must verify Clerk session tokens and check user roles before performing privileged actions.
4) Do not expose Clerk tokens or Stripe secret keys to the client.

## Database rules
1) Use Supabase Postgres with RLS enabled for all core tables: clinics, patients, appointments, notes, invoices, subscriptions, and payments.
2) Implement tenant-scoping: each row includes tenant_id (clinic_id) and is accessible only by the owning clinic and authorized staff.
3) Create foreign keys: appointments → patients, notes → appointments, invoices → subscriptions, etc.
4) Enforce non-null constraints for required fields; ensure per-field validation in server actions.
5) Audit tables: created_at, updated_at, created_by, updated_by.

## Validation rules
1) Use Zod schemas for all input validation (server + client).
2) Validate appointment times against clinic hours and time zones; convert to UTC for storage.
3) Validate Stripe webhook payloads using Stripe's signature checks before processing.
4) Normalize data (names, emails) to avoid duplicates and format drift.

## Security rules
1) Use HTTPS in all environments; no mixed content.
2) Protect API routes with auth middleware; ensure RBAC checks are present on every privileged path.
3) Never expose secrets on the client; use environment variables (process.env) and server-side vaults where possible.
4) Allow only whitelisted origins in CORS for Stripe webhooks and admin dashboards.
5) Implement Content Security Policy (CSP) and strict transport security headers in deployment config.

## Testing rules
1) Unit tests for utilities and data validators (Zod schemas).
2) Integration tests for core flows: user signup, clinic creation, patient on-boarding, and appointment scheduling.
3) End-to-end tests for user journeys using Playwright: sign-in, create appointment, generate AI notes, view invoice, pay with Stripe test cards.
4) Include tests for Stripe webhook handling and AI note generation paths.

## Deployment rules
1) Deploy to Vercel with environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET_KEY, STRIPE_API_KEY, OPENAI_API_KEY, etc.
2) Configure Stripe webhooks in the production environment and ensure they point to the correct API endpoints.
3) Enable automatic previews for PRs and maintain a stable main branch deployment.
4) Set up database migrations against Supabase with a versioned SQL in db/migrations.

## Things Claude must not do
- Do not bypass Clerk or Supabase RBAC checks.
- Do not embed secret keys in client-side code.
- Do not assume local file system persistence for production data; use Postgres via Supabase exclusively.
- Do not hard-code test data into production code paths.
- Do not call external services without validating response and handling errors gracefully.

## End of CLAUDE.md block

Recommended Project Structure

Stack-specific directory tree for a Next.js + Supabase + Clerk + Stripe Clinic Management SaaS:

clinic-management/
  apps/
    web/
      app/
        layout.tsx
        page.tsx
        globals.css
      components/
        Button.tsx
        Input.tsx
      hooks/
        useAuth.ts
      lib/
        supabase.ts
      styles/
        theme.css
  db/
    migrations/
      001-create-core-tables.sql
      002-add-rls-and-constraints.sql
    schemas/
      schema.sql
  lib/
    ai/
      notes.ts
    payments/
      stripe.ts
    auth/
      clerk.ts
    db/
      client.ts
      helpers.ts
  models/
    patient.ts
    appointment.ts
    note.ts
    invoice.ts
    payment.ts
  scripts/
    deploy.sh
    migrate.sh
  .env.example

Core Engineering Principles

• Single responsibility: separate UI, business logic, data access, and AI components.
• Security by default: enforce RBAC, server-side validation, and hidden secrets.
• Deterministic data contracts: strict TypeScript types and Zod schemas for all external inputs.
• Idempotent and auditable: design API routes to be idempotent where appropriate; log critical actions.
• Test-driven culture: implement unit, integration, and E2E tests for core features before shipping.

Code Construction Rules

• Use TypeScript across frontend and backend; avoid any where possible.
• Store and access all secrets only via environment variables or secret management; never hard-code keys.
• All API routes and server actions must validate inputs using Zod; type-safe return values.
• AI notes generation must be server-side; never call OpenAI/OpenAI-compatible API directly from the client with secret keys.
• Follow a consistent naming convention for files and folders; mirror models in the models/ directory.
• Do not rely on Prisma, Mongoose, or other ORMs not chosen for this stack; use Supabase client and SQL for data access.

Security and Production Rules

• Enable Row-Level Security on all core tables in Supabase.
• Validate Stripe webhooks with signature verification; process only verified events.
• Use short-lived tokens for client-server communication and rotate secrets regularly.
• Implement CSP, X-Frame-Options, and HSTS in deployment configurations.
• Regularly review dependencies for known vulnerabilities and apply patches promptly.

Testing Checklist

• Unit: validators, helpers, and utilities with fast tests.
• Integration: API routes, DB access, and auth flows.
• End-to-end: patient portal, appointment flow, and Stripe billing interactions.
• Performance: load tests on appointment note generation and AI paths (with rate limits).
• Security: test webhook verification and RBAC enforcement in simulated environments.

Common Mistakes to Avoid

• Assuming client-side secrets are safe; always keep secrets server-side.
• Over-privileging user roles; prefer least privilege and explicit checks.
• Skipping RBAC with multi-tenant data; ensure tenant scoping everywhere.
• Treating AI notes as a simple text sink; implement prompts and post-processing to maintain data quality.
• Neglecting Stripe webhook validation; never trust webhook events without verification.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ

Q1: What stack does this CLAUDE.md Template cover?

A: Next.js, TypeScript, Supabase, Clerk, Stripe, AI appointment notes, patient portal, and billing.

Q2: What should Claude do in the Copyable CLAUDE.md Template?

A: Follow the code block instructions to implement architecture, file structure, and security rules for the Clinic Management SaaS.

Q3: How is data secured in this Clinic Management SaaS?

A: RBAC with Supabase Row-Level Security, Clerk-authenticated sessions, Stripe webhook validation, and server-side AI note generation.

Q4: How do I test and deploy this template?

A: Use unit, integration, and end-to-end tests; deploy to Vercel with proper environment variables and webhook configurations.

Q5: What should Claude not do in this template?

A: Do not bypass auth, expose secrets, hard-code data, or rely on insecure endpoints.