Finance Reporting SaaS CLAUDE.md Template (Next.js, TS, Supabase, Clerk, Stripe)

Overview

A CLAUDE.md template for building a complete Finance Reporting SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, Excel ingestion, KPI dashboards, and AI commentary. This page provides a copyable CLAUDE.md code block you can paste into Claude Code to scaffold the stack, plus stack-specific rules and patterns to keep the implementation consistent.

Direct answer: This CLAUDE.md template defines the project role, architecture, file structure, security, testing, and deployment guidelines for a production-grade finance analytics product built on the specified stack.

When to Use This CLAUDE.md Template

• Starting a new Finance Reporting SaaS project with Next.js and TypeScript.
• Standardizing authentication with Clerk and subscription billing with Stripe.
• Implementing Excel (XLSX/CSV) ingestion pipelines for financial data.
• Building KPI dashboards with AI-generated commentary and insights.
• Onboarding new developers with a ready-to-paste Claude Code block.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, the CLAUDE.md template author for a Finance Reporting SaaS. Your output must be a complete Claude Code block tailored to Next.js + TS + Supabase + Clerk + Stripe + Excel ingestion + KPI dashboards + AI commentary.

Architecture rules:
- Use Next.js with the App Router under apps/web.
- TypeScript everywhere; avoid any implicit any.
- Supabase is the data layer; leverage Postgres with row-level security (RLS).
- Clerk handles authentication and user sessions; enforce role-based access control.
- Stripe manages subscriptions and billing; handle webhooks securely.
- Excel ingestion must support XLSX and CSV; map to finance entities with strict schema.
- KPI dashboards render in the frontend; provide AI commentary on KPI trends.
- All server side logic should run in TypeScript; use API routes for data access; avoid client-side data access for privileged data.

File structure rules:
- Keep config and secrets in environment variables; never commit secrets.
- API routes live under apps/web/src/app/api.
- UI components under apps/web/src/app/(dashboard)/components.
- Business logic under apps/web/src/app/(dashboard)/lib and apps/web/src/lib.
- Data access and integrations under apps/web/src/lib/integrations.

Authentication rules:
- Enforce Clerk middleware on protected routes.
- Define roles: admin, finance_analyst, viewer; guard APIs accordingly.
- Use token-based authorization for internal API calls.

Database rules:
- Supabase Postgres with tables: customers, subscriptions, invoices, kpi_metrics, ai_comments.
- Enforce tenant isolation with tenant_id; API routes require tenant context and role checks.
- Never expose admin-level credentials in client code.

Validation rules:
- Validate all inputs at API boundaries with Zod; validate Excel column mappings; sanitize every field.
- Normalize numeric inputs and dates before storage.

Security rules:
- Do not expose secrets in the frontend; use environment variables.
- Do not trust client-side validation; enforce server-side validation and authorization.
- Use parameterized queries and prepared statements; enable CSRF protection on state-changing endpoints.

Testing rules:
- Unit tests with Vitest; React components with React Testing Library.
- API integration tests with SuperTest or Playwright; mock Stripe webhooks in tests.
- End-to-end tests should cover data ingestion, auth flows, and dashboard rendering.

Deployment rules:
- Deploy on Vercel for Next.js; configure environment variables for SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_SECRET, STRIPE_API_KEY.
- Use preview deployments for PRs; run tests in CI before merge.
- Monitor health checks and log aggregation; set up alerts for failed payments, ingestion failures, and auth issues.

Things Claude must not do:
- Do not hardcode secrets.
- Do not bypass server-side validation or authorizations.
- Do not generate migrations that drop tables without explicit confirmation.
- Do not rely on client-side only data for privileged operations.
- Do not use unsupported libraries outside the stack scope.

Recommended Project Structure

finance-saas/
├── apps/
│   └── web/
│       ├── app/
│       │   ├── dashboard/
│       │   ├── analytics/
│       │   └── settings/
│       ├── components/
│       ├── hooks/
│       ├── lib/
│       ├── pages/
│       └── styles/
├── db/
│   └── migrations/
├── integrations/
│   ├── clerk/
│   ├── supabase/
│   └── stripe/
├── data/
│   └── ingestion/
└── scripts/

Core Engineering Principles

• Be explicit and auditable: every data flow and rule is documented in CLAUDE.md blocks.
• Security by default: deny until explicitly allowed; enforce least privilege.
• Type safety foremost: build with TypeScript; validate at API boundaries.
• Data integrity: strict schema, migrations, and validated data ingestions.
• Operational discipline: tests, CI, and deployment automation.

Code Construction Rules

• Use API routes for data access; never call the database directly from frontend components.
• Leverage Supabase client on the frontend only for non-privileged reads; all privileged actions go through API routes with server-side checks.
• Excel ingestion modules must validate schema before storage and provide meaningful error messages.
• All data models and API responses must be typed.
• Follow the project’s naming conventions; keep components small and reusable.

Security and Production Rules

• Enforce clerk-based authentication and role checks on protected endpoints.
• Enable Supabase Row-Level Security with tenant scoping for all relevant tables.
• Validate and sanitize all inputs; never trust client-provided data.
• Keep secrets out of the client; use environment variables and secret management tooling.
• Audit logs for authentication, payments, and data ingestion events.

Testing Checklist

• Unit tests for API handlers and business logic.
• Integration tests for auth, data ingestion, and KPI data flows.
• End-to-end tests covering login, data ingestion, and dashboard rendering.
• Stripe webhook security and idempotency in tests.

Common Mistakes to Avoid

• Assuming client validation is sufficient for security.
• Neglecting tenant isolation across data tables.
• Overexposing admin capabilities in frontend code.
• Skipping end-to-end tests for critical data paths.

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

FAQ

1. What is the purpose of this CLAUDE.md Template?

   To provide a copyable CLAUDE.md block that guides developers through building a Finance Reporting SaaS with Next.js, TS, Supabase, Clerk, Stripe, Excel ingestion, KPI dashboards, and AI commentary.

2. Which stack components are required by this template?

   Next.js (App Router), TypeScript, Supabase, Clerk, Stripe, and an Excel ingestion pathway with KPI dashboards and AI commentary.

3. How is tenant isolation enforced?

   With Supabase RLS and a tenant_id field; API routes require tenant context and role checks via Clerk.

4. How do I test Excel ingestion mappings?

   Use sample XLSX/CSV files; validate schema mapping against the defined finance entities in tests.

5. What are deployment considerations?

   Use Vercel for Next.js; configure necessary environment variables; ensure tests run in CI and before merge.