CLAUDE.md Template — Next.js TypeScript Accounting Portal with Supabase, Clerk, Stripe

Overview

The CLAUDE.md template is a copyable blueprint for building a complete Accounting Client Portal using Next.js, TypeScript, Supabase, Clerk, Stripe, AI document checklist, invoice tracking, and reports. This page provides a ready-to-paste CLAUDE.md block and stack-specific conventions to keep architectural decisions consistent across your project.

Direct answer: This CLAUDE.md Template provides a concrete set of Claude Code instructions for a Next.js + TS + Supabase + Clerk + Stripe accounting portal, including authentication, data access rules, and deployment steps.

When to Use This CLAUDE.md Template

• Starting a new Accounting Client Portal project that uses Next.js and TypeScript.
• Integrating Supabase as the backend and Clerk for authentication.
• Implementing AI document checklist, invoice tracking, and reports workflows.
• When you want a copyable CLAUDE.md template that enforces architecture and rules.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Platform Engineer building an accounting client portal using Next.js, TypeScript, Supabase, Clerk, Stripe, and AI document checklist features.
Architecture rules:
- Build with Next.js App Router, TypeScript, and strong typing across the stack.
- Centralize business rules in a small set of server-side modules; avoid duplicating logic across UI and API.
- Use a single source of truth for core entities: Client, Invoice, and Document.
File structure rules:
- Place all page-level logic under app/ with clean component boundaries.
- Keep library / lib modules for API clients (Supabase, Clerk, Stripe) and for shared utilities.
- Do not mix UI components with data access code.
Authentication rules:
- Use Clerk for authentication with sessions stored as secure HttpOnly cookies.
- Enforce email verification for privileged actions.
- Gate all sensitive routes with role checks (e.g., accountant, admin).
Database rules:
- Use Supabase with Row Level Security (RLS) enabled.
- Each tenant data must be isolated; queries must filter by companyId/tenantId.
- Invoices, payments, and documents must be linked to a specific client and portal.
Validation rules:
- Use TypeScript types with runtime validation (e.g., zod) for API inputs/outputs.
- Validate all external data (webhooks, file uploads, and form data) before processing.
Security rules:
- Never expose secrets in client-side code.
- Validate Stripe webhooks using signature; store only necessary data.
- Enforce CSRF protection for state-changing POST requests.
Testing rules:
- Unit tests for shared utilities and services (Supabase, Clerk, Stripe wrappers).
- Integration tests for critical API routes (invoices, payments, document checks).
- End-to-end tests for core flows (invoice creation, AI checklist, and reports).
Deployment rules:
- Use Vercel for hosting; configure environment variables securely.
- Set up Stripe Webhook endpoint with the secret and verify signatures in production.
- Instrument error tracking and logs, with verbose logs limited to non-prod.
Things Claude must not do:
- Do not hardcode API keys or secrets in code or CLAUDE.md.
- Do not bypass authentication or authorization checks.
- Do not trust client-side input; always validate on server.
- Do not skip testing or deploy without a proper review.

Recommended Project Structure

apps/accounting-portal/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── invoice/
│   │   └── page.tsx
│   ├── dashboard/
│   │   └── page.tsx
│   └── reports/
│       └── page.tsx
├── components/
├── lib/
│   ├── supabaseClient.ts
│   ├── clerkClient.ts
│   └── stripeClient.ts
├── hooks/
├── styles/
├── types/
├── public/

Core Engineering Principles

• Typed interfaces and strict contracts between server and client.
• Single source of truth for core domain entities.
• Clear separation of concerns between UI, data access, and business rules.
• Idempotent deployments with predictable rollbacks.
• Observability through structured logging and metrics.

Code Construction Rules

• Prefer server components for data fetching and business logic; keep client components lean.
• Use Supabase storage for documents and enforce file size/type checks on upload.
• Use Clerk for authentication; store user roles, and implement role-based guards on routes.
• Implement Stripe payments with webhook verification; never perform payment actions on the client.
• Validate inputs with zod on API boundaries; generate TypeScript types from schemas when possible.
• Keep API clients in a dedicated lib module; wrap with small, testable adapters.
• Write tests that exercise real data flows (invoices, AI checklist, reports).
• Avoid hard-coding credentials; use environment variables and secret managers.

Security and Production Rules

• Enable Supabase Row Level Security (RLS) and enforce tenant isolation on all queries.
• Use HttpOnly secure cookies for Clerk sessions.
• Verify Stripe webhooks with the signature header; log only non-sensitive event data.
• Validate all user input, enforce CSRF protection, and restrict API surface to authenticated roles.
• Keep secrets out of the repository; rotate keys regularly and monitor for exposure.

Testing Checklist

• Unit tests for shared utilities and adapters (Supabase, Clerk, Stripe).
• Integration tests for /api endpoints (invoices, payments, AI checklist).
• End-to-end tests for user flows (create invoice, run AI document checklist, generate reports).
• Performance tests for critical paths and API response times.

Common Mistakes to Avoid

• Not enabling/maintaining Row Level Security on Supabase.
• Mixing server and client concerns; leaking secrets in frontend code.
• Over-optimizing client rendering before server data fetching; ignoring accessibility.
• Skipping tests or deploying without environment parity.

Related implementation resources: AI Agent Use Case for Green Building Consultants Using Audit Reports to Prioritize Energy Efficiency Actions and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ

• What is this CLAUDE.md Template for? It provides a copyable CLAUDE.md blueprint for a complete accounting client portal built with Next.js, TypeScript, Supabase, Clerk, Stripe, and AI document checklist features.
• Which stack does it cover? Next.js, TypeScript, Supabase, Clerk, Stripe, AI document checklist, invoice tracking, and reports.
• How do I use the copyable CLAUDE.md block? Paste it into CLAUDE.md at the project root and customize identifiers to your tenant data model.
• What about security? It enforces Clerk authentication, Supabase RLS, Stripe webhook verification, and server-side validation for all inputs.
• How do I test this template? It includes unit, integration, and end-to-end test guidelines with recommended tooling and coverage.