CLAUDE.md Template: Next.js + TypeScript Personalization Engine with Supabase, Clerk, Stripe

Overview

CLAUDE.md template for building a complete AI Personalization Engine using Next.js, TypeScript, Supabase, Clerk, Stripe, embeddings, user behavior tracking, and recommendations. This page provides a copyable CLAUDE.md block you can paste into Claude Code to generate a production-ready, stack-specific blueprint.

Direct answer: Paste the CLAUDE.md block into Claude Code to generate a Next.js + TS AI Personalization Engine with Supabase, Clerk, Stripe, embeddings, and behavior tracking, ready for real-world deployment.

When to Use This CLAUDE.md Template

• You need a full-stack AI personalization stack with a modern Next.js front-end.
• You require server-first data handling via Supabase, including Row Level Security (RLS).
• Authentication is provided by Clerk; payments are handled by Stripe server-side.
• Embeddings-based recommendations and user behavior tracking are core features.
• You want a clear file structure and strict architecture rules for consistency across teams.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code. Your task is to deliver a complete AI Personalization Engine blueprint using Next.js + TypeScript, Supabase, Clerk, Stripe, embeddings, and user behavior tracking. Provide a production-ready blueprint including a copyable code block, architecture rules, file structure, and security guidelines that a developer can paste into CLAUDE.md.

Architecture rules:
- Use Next.js App Router with server components where appropriate; separate server and client concerns clearly.
- Data layer must be Supabase; do not use Prisma, Mongoose, Drizzle, or similar ORMs.
- Authentication must be implemented with Clerk; store user identity securely and avoid exposing credentials on the client.
- Payments must be processed via Stripe on the server; client can initiate checkout flows via secure session tokens.
- Embeddings and recommendations must run on the server and be cached per user session; expose only necessary results to the client.
- All secrets belong to environment variables; never commit secrets or keys to code.
- Use TypeScript types for all boundaries and validate inputs at the API layer.
- Prefer server-side rendering for data-sensitive views; minimize client data exposure.

File structure rules:
- Create a Next.js project layout with the App Router (app/), components/, lib/, services/, models/, hooks/, and styles/.
- Key files:
  - app/
  - app/(routes)/page.tsx
  - components/
  - lib/supabaseClient.ts
  - lib/clerkClient.ts
  - lib/stripeClient.ts
  - lib/embeddings.ts
  - services/personalization.ts
  - models/User.ts
  - hooks/usePersonalization.ts
  - pages/ (for any legacy routes if necessary)
  - styles/globals.css
- Do not include nonessential folders like prisma/, mongoose/, or test scaffolds at the root.

Authentication rules:
- Clerk-based authentication for all protected routes.
- Use server actions or API routes for sensitive operations (payments, embeddings generation).
- Expose only public endpoints on the client; keep secrets on the server.

Database rules:
- Supabase with Postgres and Row Level Security (RLS).
- Users table includes: id, email, plan, embeddings_rank, preferences, last_seen.
- Define policies: users can read their own profile; admins can read all; embeddings data accessible to authorized services only.
- Do not store API keys or secrets in client code.

Validation rules:
- Use Zod schemas for all input validation; export schemas in lib/schemas.ts.
- Validate all incoming API payloads and return consistent error messages.

Security rules:
- Enforce HTTPS; use secure cookies; set sameSite=Strict; rotate tokens regularly.
- Sanitize all inputs; prevent SQL injection and XSS.
- Do not log sensitive data; avoid verbose error traces in production.

Testing rules:
- Unit tests for utilities and validators.
- Integration tests for API routes and services.
- End-to-end tests (Playwright) for authentication, personalization, and checkout flows.
- CI should run tests on push to main.

Deployment rules:
- Deploy on Vercel or equivalent; configure env vars securely.
- Use edge runtime for latency-sensitive personalization paths where appropriate.
- Cache embeddings results and recommendations where beneficial.

Things Claude must not do:
- Do not hardcode secrets or API keys in code.
- Do not bypass server-side validation or privacy controls.
- Do not perform client-side embedding generation or expose embedding data to the client without safeguards.
- Do not use Prisma, Mongoose, Drizzle, or other ORMs when using Supabase.
- Do not expose private Stripe keys to the client.

Recommended Project Structure

my-app/
├── app/
│   ├── layout.tsx
│   └── page.tsx
├── components/
├── lib/
│   ├── supabaseClient.ts
│   ├── clerkClient.ts
│   ├── stripeClient.ts
│   └── embeddings.ts
├── services/
│   └── personalization.ts
├── models/
│   └── User.ts
├── hooks/
│   └── usePersonalization.ts
├── styles/
│   └── globals.css
└── README Claude.md

Core Engineering Principles

• Strong typing across all boundaries (TypeScript) and explicit API contracts.
• Server-first approach for data and security; client surface minimal and safe.
• Explicit data ownership and clear data flow from ingestion to personalization results.
• Deterministic behavior and idempotent operations for personalization updates.
• Observability through structured logging and metrics for embeddings and recommendations.

Code Construction Rules

• All API inputs must be validated with Zod; export and reuse schemas from lib/schemas.ts.
• Use clear, explicit types for all data models and responses.
• Keep embedding and recommendation logic in server-side modules; avoid leaking keys or tokens to the client.
• Refer to environment variables via process.env and use a secure runtime to load them.
• Do not mix client and server logic in the same module; maintain a clean boundary.
• Document any public API surface with JSDoc-like comments for Claude Code if used in generation.

Security and Production Rules

• Enable Supabase RLS with roles for users, admins, and services.
• Use Clerk session tokens; never store or expose secret keys on the client.
• Validate and sanitize all inputs; guard against injection and XSS.
• Protect Stripe webhooks with signature verification; log events securely.
• Keep embeddings and models on the server; cache results safely and invalidate stale data.
• Harden deployment: HTTPS only, secure cookies, proper CORS, and secrets rotation.

Testing Checklist

• Unit tests for utilities, validators, and data models.
• Integration tests for API routes: user enrollment, login, personalization generation, and checkout.
• End-to-end tests (Playwright) for authentication, personalization flows, and payment.
• Performance tests for embedding inference and recommendation latency.
• CI config to run tests on push to main and generate a report.

Common Mistakes to Avoid

• Skipping server-side validation or relying on client-side checks alone.
• Exposing embedding data or API keys in client bundles.
• Overreliance on a single provider for embeddings without fallback paths.
• Neglecting proper RBAC/RLS policies in Supabase.
• Using Prisma or Mongoose with Supabase; mismatch of data access layers.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Managing runtime hydration layers to avoid client-side compilation conflicts in production.

FAQ

What is a CLAUDE.md Template and when should I use it?

A CLAUDE.md Template is a copyable blueprint for Claude Code to generate a stack-specific solution. Use this when building an AI Personalization Engine with Next.js, TS, Supabase, Clerk, Stripe, embeddings, and behavior tracking.

Which stack does this template cover?

Next.js with App Router (server components), TypeScript, Supabase backend, Clerk for auth, Stripe for payments, embeddings for recommendations, and user behavior tracking.

How is security enforced in production?

Supabase RLS, Clerk session management, secure env vars, server-only code paths, and thorough input validation.

What tests should I run before deployment?

Unit tests for utilities/validators, integration tests for API routes and services, and Playwright end-to-end tests for critical user flows.

Where do I start?

Copy the CLAUDE.md template block into Claude Code and adapt file structure and environment settings for your project.