CLAUDE.md Template: Next.js Dental Practice SaaS with TypeScript, Supabase, Clerk, and Stripe

Overview


The CLAUDE.md template demonstrates how to assemble a complete Dental Practice SaaS using the stack: Next.js 13+ App Router, TypeScript, Supabase, Clerk, Stripe. It includes AI treatment summaries, automated reminders, and secure patient records. This page provides a copyable CLAUDE.md template you can paste into a CLAUDE.md file to bootstrap your project with Claude Code.



When to Use This CLAUDE.md Template



  - You're building a HIPAA-conscious dental practice management SaaS with modern frontend and server components.

  - You need a compact blueprint that wires Next.js, Supabase auth, Clerk authentication, Stripe billing, and AI-driven patient summaries.

  - You want a ready-to-paste CLAUDE.md instruction block that enforces architecture, file layout, and security constraints.



Copyable CLAUDE.md Template


Paste this into a CLAUDE.md file to initialize the project with Claude Code for this stack.


# CLAUDE.md
Project role: Lead Architect for a Dental Practice SaaS built with Next.js 13+ App Router, TypeScript, Supabase, Clerk, Stripe. Implement AI-driven treatment summaries, reminders, and patient records.

Architecture rules:
- Use Next.js App Router with server components for data-heavy pages; avoid getStaticProps/getServerSideProps patterns.
- TypeScript everywhere; define strict types for Patient, Treatment, Reminder, and MedicalRecord.
- Data layer via Supabase; implement Row Level Security policies; use Supabase client on server components only.
- Authentication via Clerk; protect routes with Clerk middleware; use server actions for mutations.
- Payments via Stripe; implement a subscription model with server-side webhooks; store customer and subscription IDs in Supabase.
- AI components: generate concise treatment summaries and patient-facing summaries using Claude Code; store results in patient_records.ai_summary.
- Data modelling: patients, records, treatments, reminders, invoices; enforce data ownership by tenant_id across all resources.

File structure rules:
- app/ (Next.js App Router)
- components/
- lib/
- db/ (Supabase utilities, hooks and migrations not included in code blocks)
- models/
- services/
- ai/ (Claude Code tasks and prompts)

Authentication rules:
- ClerkProvider at the app root; use getAuth from @clerk/nextjs to guard server actions and API routes.
- Do not expose public API keys in the client; route all sensitive calls through server components.

Database rules:
- Supabase tables: patients, records, treatments, reminders, invoices.
- Enable RLS; policies: only the patient owner or the tenant admin can read/write data.

Validation rules:
- Use Zod for all input validation; export TS types from a shared folder; strict parse for API inputs.

Security rules:
- Do not log PII in client logs; never embed API keys in client code.
- Use environment variables for secrets; do not hard-code secrets.
- Enforce transport security (HTTPS) and sanitize all outputs before UI rendering.

Testing rules:
- Unit tests for utilities with Vitest; integration tests for DB access using a test instance of Supabase; UI tests with Playwright.

Deployment rules:
- Deploy on Vercel; configure environment variables: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, CLERK_FRONT_END_API, CLERK_API_KEY, STRIPE_SECRET_KEY, OPENAI_API_KEY or CLAUDE_ENDPOINT.
- Use CI to run tests and lint on PRs; enable sandbox environments for data migrations.

Things Claude must not do:
- Do not bypass Clerk authentication; do not access client secrets from the UI; do not call Stripe secret keys from the client.
- Do not emit direct SQL strings in client code; do not create insecure role bypasses.


Recommended Project Structure


my-dental-saas/
  app/
    dashboard/
      page.tsx
      patient/[id]/page.tsx
    patients/
      page.tsx
  components/
  lib/
  db/
    supabase/
      client.ts
      migrations/
  models/
  services/
  ai/
  scripts/


Core Engineering Principles



  - Type-safety and explicit interfaces for all data models.

  - Security-first design, with least privilege and proper data isolation (RLS).

  - Correctness and maintainability over clever tricks.

  - Clear separation of concerns: UI, business logic, data access, and AI prompts.

  - Performance-conscious data access and caching for patient data.



Code Construction Rules



  - Use TypeScript types for all entities: Patient, Treatment, Reminder, MedicalRecord, Invoice.

  - Follow Next.js App Router conventions; server components for data access; client components only for UI that needs interactivity.

  - All API routes and server actions must be typed and validated using Zod.

  - Avoid client-side secrets; fetch secrets server-side and pass only safe data to the client.

  - Implement consistent error handling with meaningful HTTP status codes.



Security and Production Rules



  - Enable Supabase Row Level Security on all data tables and enforce policies per tenant.

  - Use Clerk for authentication and authorization; protect all sensitive endpoints.

  - Never expose Stripe keys or API keys to the client; use server routes for payments and webhooks.

  - Validate all inputs and sanitize outputs before rendering to the user.

  - Audit logs for critical actions; avoid leaking PII in logs or analytics events.



Testing Checklist



  - Unit tests for utilities and validators (Zod schemas).

  - Integration tests for database CRUD operations with Supabase (mocked in CI or dedicated test DB).

  - End-to-end tests for core flows (signup, patient creation, treatment addition, reminders, billing).

  - Security tests for role-based access and anti-privacy violations.

  - Deployment sanity checks for environment variables and webhooks.



Common Mistakes to Avoid



  - Skipping Row Level Security policies on Supabase tables.

  - Exposing API keys or secrets in client code or committed repos.

  - Mixing server and client components for data access; leaking server-only logic to the UI.

  - Neglecting data validation for inputs from the UI or API routes.

  - Ignoring HIPAA/privacy requirements in data model or logs.



Related implementation resources: AI Use Case for Geotechnical Firms Using Core Sample Records To Predict Soil Stability for Heavy Foundation Building and Why authorization checks belong in AI coding instructions for production-grade systems.





FAQ



  What stack is this CLAUDE.md Template designed for?
  Next.js (App Router) + TypeScript + Supabase + Clerk + Stripe, with AI treatment summaries, reminders, and patient records.
  What is included in the copyable CLAUDE.md block?
  A ready-to-paste instruction block covering architecture, file structure, auth, DB, validation, security, testing, deployment, and anti-patterns.
  How do AI summaries integrate with patient records?
  AI generates concise treatment summaries and patient-facing notes stored in a dedicated ai_summary field in patient_records.
  Where should secrets live?
  Secrets live only in server-side environments. Client code must not access keys; use environment variables and secure server routes.
  Where can I find the recommended project structure?
  Refer to the Recommended Project Structure section in the CLAUDE.md content.