CLAUDE.md Template: Next.js 14 + Supabase + Clerk + Stripe University Recommendations SaaS

Overview

This CLAUDE.md Template describes a complete, production-ready blueprint for a University Recommendation SaaS built with Next.js (App Router), TypeScript, Supabase, Clerk, Stripe, AI-driven profile analysis, rankings, and PDF reports. It provides a copyable Claude Code block you can paste into CLAUDE.md to orchestrate frontend, backend, authentication, payments, data models, AI analysis, ranking logic, and report generation with a focus on developer experience and security.

Direct answer: Paste the included Claude Code block into CLAUDE.md to instruct Claude Code to implement a scalable Next.js app backed by Supabase, with Clerk for auth, Stripe for payments, AI profiling, rankings, and PDF reports.

When to Use This CLAUDE.md Template

• You’re building a SaaS for higher education admissions workflows with personalized university recommendations.
• Your stack is Next.js (App Router) with TypeScript, Supabase as the backend, Clerk for authentication, and Stripe for subscriptions.
• You need AI-powered candidate profiling, ranking algorithms, and generated PDF reports for admissions committees.
• You want a copyable, architecture-aware Claude Code blueprint to avoid drift and ensure repeatable deployments.

Copyable CLAUDE.md Template

# CLAUDE.md

# CLAUDE Code Blueprint for University Recommendation SaaS (Next.js 14 + Supabase + Clerk + Stripe)

Project role
- You are Claude Code. Your mission is to implement a full-stack Next.js 14 + TypeScript SaaS on Supabase with Clerk authentication, Stripe payments, AI-driven student profile analysis, ranking, and PDF report generation.

Architecture rules
- Use Next.js App Router with server components where appropriate; separate frontend (UI) from API routes.
- Supabase acts as the primary database and storage; implement RLS policies to enforce data access per user role.
- Clerk handles authentication and user management; map Clerk users to your Supabase users securely via JWT.
- Stripe handles subscriptions; verify webhook events server-side and store customer/subscription in Supabase.
- AI analysis calls should run on server-side endpoints, not directly from client code; batch long-running tasks where possible.
- All secrets must be stored in environment variables; never hard-code keys.

File structure rules
- apps/university-recs/ (Next.js app)
  - app/
    - layout.tsx
    - page.tsx
    - (features grouped by domain: analytics/, profiles/, reports/)
  - components/
  - lib/
  - ui/
  - styles/
  - services/
  - hooks/
  - prisma/ (do not include; this stack uses Supabase, not Prisma)
- scripts/
- tests/
- lib/supabase.ts (client and server helpers)
- lib/stripe.ts (webhook handlers and helpers)
- lib/ai.ts (profile analysis and ranking utilities)
- pages/api/ (optional for custom API routes if not using app router)

Authentication rules
- Use ClerkProvider at the root; protect pages with auth.tsx wrappers; redirect unauthenticated users to Clerk sign-in.
- Map Clerk user IDs to Supabase user records; store only non-sensitive identifiers on the client.
- Enforce RBAC in server actions; only authorized roles can access student data and reports.

Database rules
- Tables: universities, students, applicants, applications, recommendations, rankings, reports, ai_profiles, subscriptions, invoices, users_map.
- Implement Row Level Security (RLS) with policies validated on writes/reads via PostgREST style guards.
- Store audit trails for ranking calculations and report generations.

Validation rules
- Use Zod schemas for all incoming API payloads; validate on both client and server; never trust client input.
- Validate AI responses for structured data formats (JSON with defined schemas).

Security rules
- Validate Stripe webhooks with signature verification; reject unknown events.
- Do not expose private keys on the client; load in server environment only.
- Enable CSRF protection for state-changing actions; use SameSite cookies.
- Use least privilege database roles and separate service roles from client roles.

Testing rules
- Unit tests for core utilities (ranking, AI profiling, PDF generation).
- Integration tests for API routes, auth flows, and Stripe webhooks.
- E2E tests simulating user signup, subscription, AI profiling, ranking results, and PDF download.

Deployment rules
- Deploy to Vercel; configure environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET_KEY, STRIPE_SECRET_KEY, OPENAI_API_KEY, PDF_LIB_KEY, etc.
- Enable production-grade caching on hot routes; use ISR where suitable for reports.
- Set up Stripe webhooks in production with proper endpoints.

Things Claude must not do
- Do not bypass Clerk authentication; do not access client-only secrets from the browser.
- Do not implement business logic in client components; keep heavy logic on the server.
- Do not rely on a single monolithic API route; break into modular server actions.
- Do not use Prisma or Mongoose in this stack (avoid frameworks not in stack).

Recommended Project Structure

apps/university-recs/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── analytics/
│   │   └── page.tsx
│   ├── profiles/
│   │   └── page.tsx
│   ├── reports/
│   │   └── page.tsx
│   └── api/
│       └── stripe-webhook.ts
├── components/
├── lib/
│   ├── supabase.ts
│   ├── stripe.ts
│   └── ai.ts
├── services/
├── styles/
├── tests/
└── scripts/

Core Engineering Principles

• Type-safe by default: rely on TypeScript everywhere and strict runtime validation (Zod).
• Security-first: enforce RBAC, secure secrets, validate webhooks, and protect API routes.
• DX-led development: small, testable units; clear interfaces between frontend, backend, and AI services.
• Data integrity: enforce server-side validation and audit trails for all user actions and AI results.
• Reliability: idempotent operations for external calls (Stripe, AI services) and robust error handling.

Code Construction Rules

• Follow the file structure rules above; maintain domain boundaries for profiles, rankings, and reports.
• Use server components where possible; avoid heavy client-side AI logic.
• API payloads must be validated with Zod schemas; reject invalid shapes with 400 errors.
• Store sensitive keys in environment variables; never commit secrets.
• Keep business logic out of UI components; create service layer wrappers in lib/ and services/.
• Respect RLS policies in Supabase and map Clerk identities to Supabase users securely.
• Do not hard-code Stripe test keys in code paths that run in production; use environment variables only.

Security and Production Rules

• Enforce strict RBAC with Clerk roles; limit data access to authorized user scope.
• Validate Stripe webhooks server-side; verify signatures before processing events.
• Use server-side API routes to perform sensitive operations (AI analysis, ranking updates, PDF generation).
• Enable TLS everywhere; set Secure and HttpOnly flags on cookies.
• Regularly rotate API keys and monitor audit logs for suspicious activity.

Testing Checklist

• Unit tests for utilities (ranking, AI profiling, PDF formatting).
• Integration tests for auth flows, API routes, and database interactions with Supabase.
• End-to-end tests simulating user sign-up, subscription, profile analysis, rankings, and PDF reports download.
• Manual smoke tests after deployments to verify Stripe webhooks and AI services integration.

Common Mistakes to Avoid

• Relying on client-side data for security decisions; always confirm on server side.
• Over-fetching data in client components; leverage server components and streaming when appropriate.
• Using Prisma in this stack; the intended backend is Supabase with Postgres; avoid Prisma migrations unless you add it intentionally.
• Ignoring accessibility in UI; ensure all reports and PDF contents are accessible where possible.
• Ignoring audit trails for AI decisions and rankings; maintain verifiable logs.

Related implementation resources: AI Use Case for Wellness Coaches Using Stripe Data To Analyze Which Subscription Models Have The Highest Retention and Why authorization checks belong in AI coding instructions for production-grade systems.

FAQ

Q: What is the CLAUDE.md Template for this stack?

A: A copyable Claude Code blueprint to implement a Next.js 14 + TS SaaS with Supabase, Clerk, Stripe, AI profiling, rankings, and PDF reports.

Q: Which files are essential to start?

A: app layout, pages for profiles and reports, lib/supabase.ts, lib/stripe.ts, ai.ts, and server-side API routes for webhooks and AI tasks.

Q: How do I secure Stripe webhooks?

A: Validate signatures in a server-safe endpoint and store events only after verification.

Q: How is user data access controlled?

A: Through Clerk authentication, mapped to Supabase users with RLS policies; enforce per-user data visibility in server actions.

Q: How are PDFs generated?

A: Server-side PDF generation using pdf-lib or similar; store generated PDFs in Supabase storage and serve via signed URLs.