CLAUDE.md template for Next.js Multi-Vendor Marketplace with Supabase, Clerk, Stripe Connect — CLAUDE.md Template

Overview

The CLAUDE.md template is a concrete, copyable blueprint for building a complete Multi Vendor Marketplace using Next.js, TypeScript, Supabase, Clerk, Stripe Connect, AI product descriptions, reviews, and seller dashboards. It provides an actionable CLAUDE.md block that you can paste into CLAUDE.md to guide Claude Code through implementation steps.

Direct answer: This template codifies stack-specific rules, a ready-to-run CLAUDE.md block, and a clear project structure so developers can reproduce a production-grade marketplace.

When to Use This CLAUDE.md Template

• When you want a fully specified stack (Next.js + TS + Supabase + Clerk + Stripe Connect) with AI-generated content features.
• When you need a reproducible CLAUDE.md instruction for a multi-vendor marketplace.
• When you want a vetted project structure and deployment guidance for Claude Code.
• When you want to codify security rules and production readiness in a single template.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude, the architecture-focused assistant responsible for delivering a production-grade multi-vendor marketplace using Next.js, TypeScript, Supabase, Clerk, Stripe Connect, AI product descriptions, and reviews. You will generate code blocks, file structure, and rigorous rules that guide developers to implement, test, and deploy with high quality.

Architecture rules:
- Use Next.js App Router with TypeScript
- Use Supabase Postgres for the database, with Row Level Security enabled
- Use Clerk for authentication and user management
- Use Stripe Connect for marketplace payments, with connected accounts per seller
- All AI-generated content (descriptions, reviews) must be produced via a controlled AI microservice and may not be injected into SQL directly
- Favor declarative configuration and explicit prompts over ad-hoc queries

File structure rules:
- Place the Next.js app under apps/web with src/ as the source root
- Follow Next.js 13+ App Router conventions; use app/ routing, and keep modules colocated within feature folders
- Do not place server-only code in client components
- Centralize configuration under /config and /env in the project root

Authentication rules:
- Clerk must be integrated at the root and used for protectRoute wrappers or serverAction auth guards
- Use session roles to distinguish buyer, seller, and admin
- Do not expose Clerk API keys on the client

Database rules:
- Supabase PostgreSQL with authenticating Row Level Security (RLS)
- Tables: vendors, products, descriptions, reviews, orders, payments
- Each table must have created_at and updated_at timestamps
- Enforce foreign keys and constraints, and model relations explicitly
- Do not bypass RLS or create privileged views for client use

Validation rules:
- Use Zod schemas for all input validation on the server
- Validate incoming payloads in API routes and server actions
- Ensure content from AI descriptions is sanitized before storage

Security rules:
- Do not store secrets in client-side code
- Use environment variables and a secure secrets manager
- Use CSRF protection for state-changing operations
- Do not log sensitive data in production

Testing rules:
- Unit tests for data validation and utilities
- Integration tests for API routes and service adapters
- End-to-end tests for critical user paths (buyer purchases, seller onboarding)
- Use Vitest for unit/integration, Playwright for E2E

Deployment rules:
- Deploy to Vercel or similar with environment-specific configs
- Ensure build-time environment variables are loaded and referenced securely
- Enable database migrations as part of CI/CD
- Use feature flags to shield incomplete features

Things Claude must not do:
- Do not reveal secret keys in code blocks
- Do not bypass authentication or security controls
- Do not write vendor-specific SQL that bypasses RLS
- Do not use deprecated APIs or libraries

Recommended Project Structure

/
  apps/
    web/
      src/
        app/
          layout.tsx
          page.tsx
        components/
        features/
          marketplace/
          products/
          sellers/
          reviews/
        hooks/
        lib/
        services/
        types/
      public/
  db/
    migrations/
    seeds/
  integrations/
    supabase/
    clerk/
    stripe/
  infra/
    cloud/
  scripts/

Core Engineering Principles

• Explicit contracts: all rules, inputs, outputs, and success criteria must be defined in CLAUDE.md.
• Single source of truth: architecture rules and data models must reflect the real deployment.
• Idempotence: code blocks and deployment steps must be safe to re-run.
• Security by default: never expose secrets; validate input and enforce RBAC.
• Measure twice, ship once: require tests before deployment; specify acceptance criteria.

Code Construction Rules

• Use TS types for all API boundaries and service adapters
• Do not bypass server-side validation; rely on Zod for all payloads
• Prefer server components and edge-friendly patterns where possible
• Do not hard-code secrets; use environment variables
• Ensure all AI content is generated through the AI microservice and sanitized before storage

Security and Production Rules

• Enable Supabase RLS; define policies per table
• Enforce CSRF protection for state-changing requests
• Do not log or expose secrets in logs
• Audit trails for critical actions (seller onboarding, payouts)

Testing Checklist

• Unit tests for critical validators and adapters
• Integration tests for API routes and service layers
• End-to-end tests for buyer and seller flows
• Static analysis and type checks in CI

Common Mistakes to Avoid

• Assuming client code can perform privileged DB operations
• Overly permissive CORS or RBAC settings
• Storing secrets in client bundles
• Skipping AI content sanitization and validation

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Enforcing AI Review Standards with Reusable Skill Files: CLAUDE.md Templates and Cursor Rules for Production-Grade Systems.

FAQ

• Q: What stack does this CLAUDE.md template cover?
  A: Next.js, TypeScript, Supabase, Clerk, Stripe Connect, with AI product descriptions, reviews, and seller dashboards.
• Q: What is included in the copyable CLAUDE.md template block?
  A: The block contains project role, architecture rules, file structure rules, authentication rules, database rules, validation rules, security rules, testing rules, deployment rules, and things Claude must not do.
• Q: How do I customize the template for my marketplace?
  A: Replace sample data models, adjust Stripe Connect accounts, tailor AI prompts, and adapt DB schemas to your business rules.
• Q: How should I structure the project?
  A: Use the recommended Next.js + Supabase layout described above, with apps/web, db, integrations, infra, and scripts directories.
• Q: Where do I start after copying the CLAUDE.md?
  A: Set environment variables, install dependencies, run tests, and deploy to your hosting provider; use the internal links for more templates.