CLAUDE.md Template for Next.js + TypeScript + Supabase + Clerk + Stripe Internal Tools Builder

Overview

This CLAUDE.md template is designed for building a complete Internal Tools Builder using Next.js with TypeScript, Supabase as the backend, Clerk for authentication, Stripe for payments, AI-driven form generation, and workflow automation. It includes robust role-based access controls (RBAC) and production-ready guidelines the Claude Code agent must follow. Direct answer: use this template to assemble a modular, secure internal-tools stack that scales from MVP to production.

When to Use This CLAUDE.md Template

• You need a full-stack internal tools app with a modern frontend (Next.js) and a cloud-backed backend (Supabase).
• You require RBAC and secure auth with Clerk and Stripe-based billing for tool usage.
• You want AI-driven form generation to replace repetitive form creation and validation tasks.
• You need workflow automation to connect forms, approvals, and external services (webhooks, tasks, queues).
• You prefer a TypeScript-first approach with strict type-safety across frontend, API routes, and data layer.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude Code, an AI assistant that designs and implements a complete Internal Tools Builder stack using Next.js, TypeScript, Supabase, Clerk, Stripe, AI form generation, and workflow automation with RBAC.

Architecture rules
- Build a Next.js 14+ app using the App Router.
- Use a single shared backend (Supabase) with Row-Level Security and role-based policies.
- Integrate Clerk for authentication and user management.
- Use Stripe for pay-per-seat or tiered access if monetizing internal tooling.
- Separate concerns: frontend app, backend API routes, and infra/config as isolated modules.
- Favor server components for data-heavy pages; keep computational logic in API routes.
- Centralize business logic in a small number of well-scoped services.

File structure rules
- apps/web/app/ - Next.js app (App Router)
- apps/web/public/ - static assets
- src/lib/ - external service clients (supabase, clerk, stripe)
- src/features/ - feature-based modules (ai-form, workflows, access)
- src/hooks/ - reusable hooks
- scripts/ - deployment and migration utilities
- .env.* - environment variables per environment

Authentication rules
- Clerk handles sign-in, sign-up, and session management.
- Protect all API routes and server components with Clerk guards.
- Roles map to RBAC rules in Supabase (admin, staff, user, viewer).

Database rules
- Supabase Postgres with Row-Level Security; policies depend on role.
- Use JSONB for dynamic form schemas; store form templates, responses, and audit logs.
- Include audit trail by logging create/update/delete in a dedicated table.

Validation rules
- Client forms validated with Zod; server routes validate payloads using Zod schemas.
- All form submissions must pass server-side validation before DB writes.

Security rules
- Do not expose secret keys on the client; use environment variables.
- Enforce RBAC on all endpoints; never allow elevated privileges by default.
- Verify webhook signatures for Stripe; store only necessary data.
- Enable CSRF protection for state-changing actions.

Testing rules
- Unit tests for UI components and utility functions.
- Integration tests for API routes (auth, RBAC, data access).
- End-to-end tests for critical workflows (form creation, submission, approvals).
- Run tests in CI on pull requests; ensure linting and type checks pass.

Deployment rules
- Deploy to a modern host (Vercel) with labeled environments.
- Set environment variables for Supabase, Clerk, Stripe in secrets manager.
- Configure Stripe webhooks in production; verify signatures.
- Run database migrations through a controlled process; never manual SQL in app code.

Things Claude must not do
- Do not bypass authentication checks or fetch data without authorization.
- Do not modify production DB schemas without migrations and review.
- Do not leak API keys or secrets in logs or UI.
- Do not assume database structure; validate expectations against defined schemas.

"""

Recommended Project Structure

my-internal-tools/
├─ apps/
│  └─ web/
│     ├─ app/
│     │  ├─ layout.tsx
│     │  ├─ page.tsx
│     │  └─ ...(routes)
│     └─ public/
├─ src/
│  ├─ lib/
│  │  ├─ clerk.ts
│  │  ├─ supabase.ts
│  │  └─ stripe.ts
│  ├─ features/
│  │  ├─ ai-form/
│  │  │  └─ components/
│  │  ├─ workflows/
│  │  └─ access/
│  └─ hooks/
├─ scripts/
└─ .env.example

Core Engineering Principles

• Type-safety by default: TypeScript everywhere; strict null checks enabled.
• Security by design: RBAC enforced at API and data layer; secrets never on client.
• Modular, composable architecture: clear boundaries between frontend app, API, and services.
• Declarative data contracts: schemas defined up-front and validated at the boundary.
• Observability: structured logging, metrics, and tracing for all critical flows.

Code Construction Rules

• Use Next.js App Router with TS; keep server components for data fetching and business logic.
• Centralize service clients (Supabase, Clerk, Stripe) in src/lib with typed interfaces.
• All API routes must enforce Clerk authentication and RBAC checks.
• Forms: generate with AI module, validate with Zod on client and server.
• Workflow automation: model as combinable steps with idempotent operations.
• Use environment-specific config; store secrets in protected vaults.
• Tests: unit + integration; CI runs lint, tests, and type checks on PRs.
• Deployment: migrate DB via migrations, not ad-hoc SQL in app code.

Security and Production Rules

• RBAC is enforced via policy engine; roles map to resource permissions.
• Webhooks validated, signatures checked, and events mapped to idempotent actions.
• All secrets and API keys stored in secure vaults; never hard-coded.
• Enable CSRF protection for non-idempotent POST actions; use same-site cookies.
• Audit logging for sensitive actions; retain logs per policy.

Testing Checklist

• Unit tests for UI components and utilities.
• API route tests for auth, RBAC, and data access rules.
• Integration tests for form generation and workflow execution.
• End-to-end tests for critical user journeys (form creation, submission, approvals).
• CI performs linting, type checks, and test suite; deployment gates require green status.

Common Mistakes to Avoid

• Bypassing RBAC or granting overly broad permissions to API routes.
• Storing secrets in client code or environment leakage through logs.
• Skipping server-side validation in favor of client-only checks.
• Inline database migrations or ad-hoc schema changes in application code.
• Under-architecting AI form generation; failing to validate and version schemas.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps.

FAQ

What is this CLAUDE.md Template for?

It provides a copyable Claude Code blueprint to build a complete Internal Tools Builder using Next.js, TypeScript, Supabase, Clerk, Stripe, AI forms, and workflows with RBAC.

Which stack is covered?

Next.js (App Router) with TypeScript, Supabase as the backend, Clerk for auth, Stripe for payments, and modules for AI form generation and workflow automation.

How do I test RBAC rules?

Write unit tests for permission checks and integration tests that simulate role-based access across API routes and data queries.

How are Stripe events secured?

Stripe webhook signatures are verified server-side; only validated events trigger billing-related logic.

Can I customize AI form generation?

Yes; extend the AI form module to generate schemas, validation rules, and dynamic UI, then validate with Zod before submission.