CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe + Embeddings - Analytics for AI Product Recommendation Ecommerce

Overview

A CLAUDE.md template for building a complete AI Product Recommendation ecommerce app using Next.js, TypeScript, Supabase, Clerk, Stripe, embeddings, personalization, and analytics. This page provides a copyable CLAUDE.md block you can paste into Claude Code to scaffold a production-ready stack with strong architectural guidance and constraints for a high-signal e-commerce experience.

Direct answer: This CLAUDE.md template gives you a full, ready-to-paste Claude Code blueprint covering auth, data, embeddings, recommendations, payments, analytics, and personalization for a Next.js + TS + Supabase + Clerk + Stripe stack.

When to Use This CLAUDE.md Template

• You are building an AI-powered product recommendation engine inside an ecommerce app.
• You require a coherent pattern across authentication (Clerk), payments (Stripe), and data (Supabase) with embeddings for similarity search.
• You want a copyable Claude Code outline to accelerate onboarding for new engineers and maintain security and production rules.
• You need stack-specific guidance for validation, testing, and deployment in a Next.js + TypeScript environment.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are an AI software design assistant that builds a complete AI Product Recommendation Ecommerce App using Next.js, TypeScript, Supabase, Clerk, Stripe, embeddings, personalization, and analytics. Produce concrete, production-ready Claude Code blocks, not explanations.

Architecture rules:
- Use Next.js 14+ App Router with server components where beneficial
- Centralize data access through a single Supabase client; never embed secret keys on the client
- Use Clerk for authentication; protect checkout and admin routes on the server side
- Use Stripe for payments; verify webhooks on the server and store customer metadata
- Use embeddings to power product recommendations; store vectors in Supabase (pgvector) and cache results
- Favor edge-cached, SSR/SSG rendering for product detail pages; hydrate recommendations on the client only when necessary
- Keep UI concerns separated from business logic; expose only necessary data to the client

File structure rules:
- Follow a feature-based structure under src/ with app/ and lib/
- Place API handlers under src/app/api/ and route handlers for server logic under src/app/(server)/
- Centralize utilities under src/lib/
- Store embeddings and ML utilities under src/lib/ml/
- Do not commit secrets or keys to version control; use environment variables

Authentication rules:
- All checkout and user-sensitive endpoints require Clerk authentication
- Admin endpoints require a server-side role check and an allowlist
- Never trust client-provided user IDs; always verify Clerk session on the server

Database rules:
- Supabase with tables: users, products, embeddings, recommendations, analytics_events, orders, line_items
- embeddings: product_id (FK), vector (vector), metadata (json)
- Use foreign keys for users, products; enforce non-null constraints where applicable
- Validate inputs for create/update to prevent SQL injection or invalid data

Validation rules:
- Use Zod schemas for all API payloads
- Validate request bodies on both client and server; return clear error messages and proper HTTP status codes
- Normalize and sanitize inputs; guard against XSS in product descriptions

Security rules:
- Do not expose API keys or secrets to the client
- Use server-side sessions for sensitive operations; never rely on client trust
- Validate Stripe webhook signatures; store only necessary webhook data
- Use CSRF protection for state-changing requests in the admin UI

Testing rules:
- Unit tests for utilities: embeddings, vector similarity, price calculations
- Integration tests for API handlers: auth, products, embeddings, and Stripe webhooks
- End-to-end tests for product discovery, add-to-cart, checkout, and order flow
- Use mock databases for unit tests and a real sandbox Supabase instance for integration tests

Deployment rules:
- Deploy on a platform like Vercel; ensure serverless functions scale and respect cold-start costs
- Environment variables: SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_FRONTEND_API, CLERK_API_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
- Enable caching where beneficial; invalidate on product/embedding updates
- Monitor with analytics and error tracking; alert on Stripe webhook failures

Things Claude must not do:
- Do not propose insecure patterns like embedding secrets in client code
- Do not bypass server validation for payments or authentication
- Do not assume embeddings alone will solve all recommendations without feature engineering
- Do not ignore GDPR/CCPA data considerations for analytics and personalization

Recommended Project Structure

src/
  app/
    layout.tsx
    page.tsx
    (routes for products, checkout, account, analytics)
    /api/
      embeddings.ts
      recommendations.ts
      stripe-webhook.ts
  components/
    ProductCard.tsx
    RecommendationRail.tsx
    CartButton.tsx
  lib/
    supabaseClient.ts
    clerkClient.ts
    stripeClient.ts
    embeddings.ts
    analytics.ts
  models/
    product.ts
    user.ts
  styles/
    globals.css

Core Engineering Principles

• Single source of truth for data access via Supabase client
• Server-first by default; minimize client data exposure
• Respect strong typing with TypeScript across API boundaries
• Security by design: authentication, authorization, and input validation
• Observability: structured analytics events and meaningful error reporting

Code Construction Rules

• Write strongly-typed API handlers; export clear payload types
• Abstract data access behind a lib/db layer; avoid duplicating queries
• Keep embedding logic modular; expose a function to fetch similar products by vector
• Utilize server components for UI rendering where appropriate
• Always validate and sanitize inputs; enforce schema validation on all endpoints

Security and Production Rules

• Authenticate all sensitive routes with Clerk; verify sessions on the server
• Verify Stripe webhooks using signature verification; do not trust payloads behind the client
• Store secrets in environment variables; never log them
• Implement rate limiting on high-risk endpoints
• Mask or omit PII in analytics events; comply with privacy regulations

Testing Checklist

• Unit tests for embedding and similarity search utilities
• Integration tests for auth, product fetch, recommendations, and checkout
• E2E tests simulating a user journey from product discovery to checkout
• Regression tests for price, tax, and revenue calculations
• Deployment smoke tests to verify environment variables and webhooks

Common Mistakes to Avoid

• Exposing secret keys on the client side or in logs
• Relying solely on client-side validation for critical operations
• Overusing embeddings without caching or invalidation strategies
• Ignoring analytics data privacy and consent requirements

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Persistent document caching to cut re-embedding costs in production RAG pipelines.

FAQ