CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe AI Marketplace

Overview

CLAUDE.md template for building a complete AI Automation Marketplace using Next.js, TypeScript, Supabase, Clerk, and Stripe. This template focuses on public workflows, creator payouts, and execution history, enabling rapid production-grade deployment of an AI marketplace with robust auth, payments, and auditability.

Direct answer: This CLAUDE.md Template provides a blueprint to implement a Next.js + TypeScript AI marketplace with the stack components, aligned architecture, and Claude Code you can paste directly into CLAUDE.md.

When to Use This CLAUDE.md Template

• You are building an AI automation marketplace with public workflows and need solid auth, payments, and audit trails.
• You require tight integration between Next.js frontend, Supabase PostgreSQL backend, Clerk authentication, and Stripe payouts.
• You want a maintainable architecture with clear separation of concerns and testable components.
• You need a reproducible project structure that supports creator subscriptions, workflow execution history, and payout reporting.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior full-stack engineer specializing in Next.js (App Router), TypeScript, Supabase (PostgreSQL), Clerk authentication, and Stripe payments. Produce precise, production-ready code blocks and rules for this stack.

Architecture rules:
- Use Next.js App Router with server components by default; client components only when necessary for interactivity.
- Centralize data access through a single Supabase client wrapper; avoid direct DB calls from React components.
- Implement Clerk for authentication and RBAC; enforce role-based access at the API layer.
- Integrate Stripe for payouts with webhooks; store Stripe customer and payout data in Supabase.
- Favor server-side validation and type-safe API routes; emit events to maintain an execution history log.
- Use environment-specific configuration; never hard-code secrets.
- Keep business logic out of UI and consolidate in service modules.

File structure rules:
- src/app: UI and routes
- src/lib: shared clients and utilities (supabase, clerk, stripe)
- src/components: reusable UI pieces
- src/types: TypeScript types and guards
- src/server: API routes and server actions
- db/schema.sql: Supabase schema with RLS policies
- tests/: unit and integration tests

Authentication rules:
- Use Clerk for login, signup, and multi-factor authentication if available.
- Require a verified user for protected endpoints; enforce roles: admin, creator, user.
- Token handling must be server-side; never expose keys to the client.

Database rules:
- Supabase with RLS enabled; policies must restrict select/insert/update appropriately per role.
- Tables: users, creators, workflows, executions, payouts, payments, products, subscriptions.
- Store audit data for execution history and payout events.

Validation rules:
- Validate all inputs via TypeScript types and runtime guards before DB access.
- Normalize data (lowercase emails, trim strings) before persistence.
- Validate Stripe webhook signatures on receive.

Security rules:
- Never embed secret keys in frontend code.
- Use httpOnly cookies for sessions where applicable.
- Enforce CORS and CSRF protections for API routes.
- Enable Stripe webhook signing and verify all events server-side.

Testing rules:
- Unit tests for business logic and validators.
- Integration tests for API routes (auth, payments, workflows).
- End-to-end tests for critical user journeys (signup, create workflow, run, payout).

Deployment rules:
- Deploy to a provider that supports server components (Vercel, Netlify).
- Use environment variables managed by the host; rotate keys regularly.
- Set up webhook endpoints in Stripe to point to a public URL; confirm test mode events.

Things Claude must not do:
- Do not hard-code production secrets in code blocks.
- Do not bypass authentication or authorization checks.
- Do not rely on client-side data for security decisions.
- Do not assume a specific database engine if not part of the stack.
# End CLAUDE.md

Recommended Project Structure

/apps/marketplace/
  app/
    layout.tsx
    page.tsx
    globals.css
  components/
  lib/
    supabaseClient.ts
    clerkClient.ts
    stripeClient.ts
  db/
    schema.sql
    migrations/
  types/
  styles/
  next.config.js
  tsconfig.json
  package.json
  README.md

Core Engineering Principles

• Keep authentication, authorization, and payments at the edge with secure, typed boundaries.
• Prefer server components for data fetching; minimize client state and side effects.
• Design with clear data ownership: workflows, executions, creators, payouts, and users.
• Make the CLAUDE.md template deterministic and auditable for production workflows.
• Automate validation, tests, and deployments; treat schema as a contract.

Code Construction Rules

• Use TypeScript everywhere; define strict types for API payloads and DB rows.
• Encapsulate DB access behind a service layer; export only typed interfaces.
• Schema-first development: define db/schema.sql and align with TypeScript types.
• Implement Stripe webhooks with signature verification and idempotency controls.
• Follow the Claude Code copyable block as the single source of truth for stack rules.
• Do not import client-only libraries into server code unless necessary for UI.

Security and Production Rules

• Enable row-level security (RLS) on all sensitive tables in Supabase.
• Store secrets in environment variables; rotate on a fixed schedule.
• Validate all external payloads; reject untrusted data early.
• Use signed cookies or secure sessions when handling user state.
• Protect webhook endpoints and verify Stripe signatures on receipt of events.

Testing Checklist

• Unit tests for validators and business logic.
• Integration tests for auth flows, API routes, and Stripe webhook handling.
• End-to-end tests for core user journeys: signup, create workflow, run, payout, and history view.
• Deployment smoke tests in preview environments.

Common Mistakes to Avoid

• Assuming client-side state is secure; always enforce rules server-side.
• Hard-coding Stripe keys or API secrets in code blocks.
• Neglecting audit trails for executions and payouts.
• Ignoring Supabase RLS policies or misconfiguring them.

Related implementation resources: AI Use Case for Makeup Artists Using Booking Histories To Predict Product Replenishment Timelines for Their Kits and Track Real-Time System Health on Public Layouts: Production-Grade Dashboards for Enterprise.

FAQ

• What is a CLAUDE.md Template? A copyable Claude Code instruction block that defines how to implement a specific stack in a production-ready way.
• Which stack does this template cover? Next.js with TypeScript, Supabase, Clerk, and Stripe for an AI marketplace with public workflows and payouts.
• How do I customize this template for my use case? Replace placeholders in the CLAUDE.md block with your project IDs, table schemas, and environment variables; adapt data models to your domain while preserving the rules.
• How do I deploy securely? Use a provider with server components support, load environment variables securely, verify Stripe webhooks, and enable RLS on all critical tables.
• Can Claude modify production data? No; Claude must output only blueprint instructions and code templates, not direct production changes without explicit prompts and tests.