CLAUDE.md Template for Next.js Consulting Delivery Portal

Overview

A CLAUDE.md template for building a complete Consulting Delivery Portal with Next.js, TypeScript, Supabase, Clerk, Stripe, AI project summaries, milestones, and client dashboards. This page is a copyable CLAUDE.md template you can paste into Claude Code to scaffold a production-ready portal stack. Direct answer: this template defines roles, architecture constraints, and hard rules to keep the implementation aligned with the stack.

When to Use This CLAUDE.md Template

• You are building a client-facing consulting portal with authenticated access and billing.
• You need AI-powered project summaries, milestones, and client dashboards inside Next.js.
• You require a TS-first, strongly typed architecture using Supabase as the data layer and Clerk for auth.
• You want deployment guidance for Vercel and reliable webhooks for Stripe.

Copyable CLAUDE.md Template

# CLAUDE.md

Project: Next.js Consulting Delivery Portal

ROLES
- Project role: act as a hands-on builder for a production-ready consulting delivery portal stack (Next.js, TypeScript, Supabase, Clerk, Stripe). Provide concrete, actionable steps and guardrails.

ARCHITECTURE RULES
- Framework: Next.js with App Router; TypeScript; server components where possible
- Data: Supabase Postgres with Row Level Security; API layer to enforce policies
- Auth: Clerk for authentication and user management; ensure protected routes server-side
- Payments: Stripe for subscriptions and invoicing; verify webhooks on the server
- AI: AI project summaries and milestones exposed in client dashboards
- Deployment: Vercel with environment variables secured via Secrets
- Observability: basic logging and error reporting; graceful fallbacks

FILE STRUCTURE RULES
- apps/portal/src/app/              // app router routes
- apps/portal/src/components/       // reusable UI components
- apps/portal/src/lib/              // client/server helpers (db, auth, payment)
- apps/portal/src/services/         // integration logic (Stripe, AI summarization)
- apps/portal/src/hooks/            // React hooks
- apps/portal/public/                 // static assets
- apps/portal/styles/                 // styling

AUTHENTICATION RULES
- Use Clerk provider in _app or root layout
- Server actions must validate Clerk sessions for sensitive data
- Do not serve protected data to unauthenticated users

DATABASE RULES
- Supabase with Row Level Security enabled
- Create policies for user, admin, and client roles
- Validate all queries against allowed scopes; never trust client state

VALIDATION RULES
- Use Zod for input and output schemas
- Validate all API inputs on the server side
- Ensure strict type checks across services

SECURITY RULES
- Do not expose secrets in client code
- Verify Stripe signatures for webhooks
- Enforce TLS; use secure cookies; set HttpOnly & SameSite
- Prefer server-side rendering for sensitive data

TESTING RULES
- Unit tests for components; mock external services
- Integration tests for API routes with Supabase client mocks
- End-to-end tests for critical user journeys (auth, portal, billing)

DEPLOYMENT RULES
- Deploy to Vercel; configure environment variables (SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_FRONTEND_API, CLERK_API_KEY, STRIPE_SECRET)
- Set up Stripe webhooks in prod; validate signatures
- Enable monitoring and error tracking in production

THINGS CLAUDE MUST NOT DO
- Do not bypass authentication or authorization checks
- Do not embed secrets in client code or logs
- Do not use client-only DB access for protected data
- Do not bypass validation or type checking

Recommended Project Structure

apps/portal/
  src/
    app/
      dashboard/
      milestones/
      projects/
      ai/
      api/
    components/
    hooks/
    lib/
      supabaseClient.ts
      clerkClient.ts
      stripeClient.ts
    services/
    styles/
  public/
  styles/
  scripts/

Core Engineering Principles

• Type safety first: TS everywhere; clear data contracts with Zod
• Security by default: strong auth, least privilege, and verifiable webhooks
• Server-first architecture: use server components and API routes for data access
• Single source of truth: central data layer in Supabase with policies
• Observability and reliability: logging, monitoring, and graceful error handling
• Performance-minded: caching and selective SSR/SSG where appropriate

Code Construction Rules

• Follow a TS-first approach; define interfaces for all data shapes
• Use Next.js App Router with server components for data fetching
• Supabase data access via a dedicated lib with SRP-compliant API calls
• Auth via Clerk; protect routes server-side; avoid leaking user data
• Stripe integration via official SDKs; verify webhooks; store customer data securely
• All inputs validated with Zod at API boundaries
• Do not hardcode credentials; rely on environment variables
• Do not bypass type safety for speed; prefer typed functions

Security and Production Rules

• Enable Supabase Row Level Security with well-defined policies
• Use Clerk for authentication and enforce authorization for sensitive endpoints
• Validate Stripe webhooks on the server; don’t trust client data
• Store secrets in environment variables; never in code or logs
• Force TLS, secure cookies, and proper CSRF protections where applicable
• Audit logs for critical actions (Billing, user roles, data access)

Testing Checklist

• Unit tests for UI components and hooks
• Integration tests for API routes with mock Supabase and Clerk
• End-to-end tests covering authentication, portal access, AI summaries, and billing flows
• Regression tests for role-based access controls
• Pre-deploy checks: type checks, linting, and security scan

Common Mistakes to Avoid

• Revealing keys in the frontend or logs
• Skipping server-side checks and relying on client state for access control
• Ignoring Supabase RLS policies or misconfiguring roles
• Skipping webhook verification or not handling retries
• Ignoring accessibility and localization in dashboards

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Why authorization checks belong in AI coding instructions for production-grade systems.

FAQ