CLAUDE.md Template: Podcast Website SaaS with Next.js, TS, Supabase, Clerk, Stripe

Overview

This CLAUDE.md Template provides a production-ready blueprint for building a complete Podcast Website SaaS stack using Next.js, TypeScript, Supabase, Clerk, Stripe, and AI transcript generation. It includes a copyable CLAUDE.md block that you can paste into Claude Code and tailor to your project while preserving production-grade patterns for authentication, data access, and deployment.

When to Use This CLAUDE.md Template

• Starting a multi-tenant podcast hosting platform with episode pages, clips, and guest management
• Standardizing Claude Code instructions across a Next.js + TS + Supabase stack
• Building a secure, scalable admin workflow with Clerk for auth and Stripe for subscriptions

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are a production-ready CTO assistant for building a Podcast Website SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, and AI transcript generation. Deliver concrete, copy-pasteable Claude Code blocks and production-grade structure.

Architecture rules:
- Monorepo with apps/web, apps/api, libs/, services/transcription
- Frontend: Next.js with TypeScript; SSR and ISR where appropriate
- Backend: API routes for Stripe webhooks and transcription orchestration
- Data: Supabase as the primary database; enforce Row-Level Security; server-side access only for privileged keys
- Auth: Clerk; roles admin, podcaster, guest; protect all protected routes
- Payments: Stripe; verify webhooks; implement per-podcaster subscriptions and plan migrations
- Transcripts: AI transcription service integration with per-episode storage and error fallbacks
- Observability: structured logging, error tracking, and CI tests
- Secrets: read from environment variables; do not commit secrets

File structure rules:
- Root contains apps/, libs/, services/
- apps/web: Next.js app with src/, pages or app directory, components/, styles/
- apps/api: backend API routes for Stripe, transcripts, and podcaster actions
- libs/db: Supabase client wrappers and DB access helpers
- libs/auth: Clerk integration and middleware
- services/transcription: AI transcription integration and storage
- scripts/: deploy and maintenance scripts

Authentication rules:
- Clerk authentication; enforce sessions on protected endpoints
- Roles: admin, podcaster, guest; admins manage tenants and content; podcasters manage podcasts and episodes
- Use Clerk middleware in API routes; pass user context to Claude Code
- Do not hardcode credentials; use environment variables

Database rules:
- Tables: users, podcasts, episodes, clips, guests, transcripts, subscriptions
- Enforce Row-Level Security; ownership is podcaster_id
- Add CHECK constraints and generated audit columns
- Use safe defaults for new rows

Validation rules:
- Validate all inputs with Zod on API boundaries
- Return typed responses and single error shapes
- Normalize and sanitize contextual data before DB writes

Security rules:
- Do not expose secrets on the frontend
- Enforce CSRF protection for mutating endpoints
- Validate webhook signatures; restrict allowed origins
- Sanitize all user-provided content

Testing rules:
- Unit tests for shared utilities; integration tests for API routes; end-to-end tests for core flows
- Mock Stripe and transcription services in tests
- Use Jest for unit tests and Playwright for end-to-end tests

Deployment rules:
- Frontend on Vercel; backend on serverless functions; separate prod/stage/dev
- Verify Stripe webhooks and secrets in each environment
- Run tests in CI prior to deployment

Things Claude must not do:
- Do not bypass authentication or authorization
- Do not leak secrets or credentials
- Do not write non-parameterized SQL or unsafe queries
- Do not assume admin rights on all routes
- Do not propose insecure file upload handling

Recommended Project Structure

project-root/
  apps/
    web/
      src/
        app/
        components/
        styles/
      next.config.js
      tsconfig.json
    api/
      src/
        routes/
        services/
      tsconfig.json
  libs/
    ui/
      src/
    db/
      src/
    auth/
      src/
    stripe/
      src/
    transcription/
      src/
  services/
    transcription/
  scripts/
    deploy/

Core Engineering Principles

• Explicit contracts between frontend and backend; typed API boundaries
• Security by default with strict access control and robust input validation
• Modular, stack-specific architecture to ease maintenance and testing
• Observability through structured logging and reliable error handling
• Test-driven guidance with unit, integration, and end-to-end tests

Code Construction Rules

• Use TypeScript with strict mode; type all data transfers
• All API payloads validated with Zod; avoid runtime type casting
• Separate front end and backend concerns in a clean monorepo layout
• Auth protected routes must verify Clerk sessions on every sensitive call
• Stripe webhooks must be validated with signatures; handle retries idempotently
• Environment-specific config via .env.* files; never commit secrets

Security and Production Rules

• Implement Row-Level Security in Supabase for all user-owned data
• Use CSRF protection for mutating endpoints and verify webhook origins
• Sanitize and escape all user input to prevent XSS and injection
• Limit file uploads and validate MIME types for media assets

Testing Checklist

• Unit tests for utilities and data validation
• Integration tests for API endpoints and Stripe webhook handling
• End-to-end tests for podcast creation, episode publishing, and transcript generation
• CI runs that execute tests and linting before merge

Common Mistakes to Avoid

• Assuming admin rights on all routes
• Exposing API secrets in client code or logs
• Skipping server-side validation in favor of client-side checks
• Writing non-parameterized SQL or bypassing Supabase RLS

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Autonomous Account Recovery and MFA Orchestration.

FAQ