CLAUDE.md Template: Next.js Supplier Risk SaaS with AI Scoring

Overview


The CLAUDE.md template is a copyable Claude Code blueprint for building a complete Supplier Risk SaaS using Next.js, TypeScript, Supabase, Clerk for authentication, Stripe for payments, AI vendor scoring, delivery risk analytics, and procurement dashboards. It provides concrete guidelines, file structure, data model references, and execution rules to ensure a production-ready solution. Direct answer: this template yields a ready-to-paste CLAUDE.md block that you can drop into your project to guide implementation end-to-end.


When to Use This CLAUDE.md Template



  - You are building a supplier risk platform with vendor scoring, delivery risk, and procurement analytics.

  - You require secure authentication and payments (Clerk + Stripe).

  - You want a scalable Next.js + TypeScript front-end with a Supabase backend.

  - You need a repeatable, codified CLAUDE.md template for policy-driven development.

  - You want a ready-to-paste Claude Code block that enforces architecture and security constraints.


Copyable CLAUDE.md Template


# CLAUDE.md

Project role: You are a Senior Full-Stack Engineer tasked with delivering a production-ready Supplier Risk SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI vendor scoring, delivery risk, and procurement dashboards. Assume a multi-tenant architecture with strong data isolation and role-based access.

Architecture rules:
- Use Next.js App Router with server components for data-heavy paths; client components only where necessary.
- Separate frontend, API, and data layer; minimal client-side logic for security-sensitive operations.
- Supabase as the primary Postgres database; use Row Level Security (RLS) for tenant data isolation.
- Clerk handles authentication; enforce roles for admin, analyst, procurement, and vendor users.
- Stripe handles subscriptions and payments; validate webhooks server-side and keep secrets out of the client.
- AI vendor scoring should be a server-side evaluation service with async jobs; store scores in a dedicated table with history.
- All API routes must validate input with a typed schema (Zod-like) and reject unknown fields.
- Logging to a centralized sink; do not log PII.
- Use feature flags for rollout and blue/green deployment when possible.

File structure rules:
- Keep a predictable Next.js structure: apps/supplier-risk-frontend/src/app, components, lib, services, and hooks.
- Place API routes under apps/supplier-risk-frontend/src/pages/api or app/api depending on the router.
- Centralize data access in lib/db and services/db for tests and mocks.
- Avoid mixing business logic into UI components; isolate domain logic in services/
- Include a dedicated tests/ folder at the repo root with unit, integration, and e2e tests.

Authentication rules:
- Use Clerk for all user onboarding and sessions; enforce roles via server middleware.
- Require authentication for all data-modifying endpoints; enforce tenant scoping at the DB layer.
- Do not store access tokens on the client beyond a short expiry window; refresh tokens via Clerk.

Database rules:
- Supabase with a well-structured schema: tenants, users, vendors, procurementOrders, riskScores, deliveries, dashboards.
- Implement Row Level Security (RLS) with tenant_id as the primary data partition key.
- Store AI scores with a candidate_score and scoring_timestamp; index on vendor_id and tenant_id.
- Enforce referential integrity via foreign keys; use proper constraints for deletions.

Validation rules:
- All external inputs validated with a strict schema (TypeScript types + Zod-like validation).
- Validate request bodies, query params, and path parameters; reject malformed payloads with actionable errors.

Security rules:
- Do not ship secrets to the browser; use environment-scoped keys and server-side retrieval.
- Implement rate limiting on sensitive endpoints; protect API routes from abuse.
- Ensure CSP, CORS, and content security policies align with deployment.
- Validate Stripe webhooks with signature verification; never trust client-origin data for critical decisions.

Testing rules:
- Unit tests for services and data access with mocks.
- Integration tests around authentication, database interactions, and Stripe webhooks.
- E2E tests for the core user flows: signup, vendor scoring, risk dashboard, and procurement reports.
- Lint and type checks in CI; fail fast on TS and lint errors.

Deployment rules:
- Deploy to a stable hosting environment (e.g., Vercel) with preview environments.
- Use environment variables for secrets; configure Stripe and Clerk credentials per environment.
- Set up CI to run tests, type checks, and lint on pull requests.
- Instrument error monitoring and alerts in production.

Things Claude must not do:
- Do not bypass server-side validation for API routes.
- Do not access secrets from the client or store keys in client state.
- Do not implement direct vendor scoring in the frontend; keep it as a server-side job.
- Do not rely on unknown external services for core business logic without validation.

Recommended Project Structure

apps/supplier-risk-frontend/
├── src/
│   ├── app/
│   │   ├── dashboard/
│   │   │   ├── page.tsx
│   │   │   └── components/
│   │   ├── vendors/
│   │   │   ├── page.tsx
│   │   │   └── components/
│   │   ├── auth/
│   │   │   ├── sign-in.tsx
│   │   │   └── sign-up.tsx
│   │   └── (other routes)/
│   ├── components/
│   ├── lib/
│   │   ├── db.ts
│   │   └── auth.ts
│   ├── services/
│   │   ├── vendorScoreService.ts
│   │   └── procurementService.ts
│   ├── hooks/
│   └── styles/
├── pages/
│   └── api/
│       └── (... API routes ...)
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/

db/  (supabase migrations and seed data)
services/ (external integrations and AI scoring workers)
scripts/ (deployment and maintenance scripts)

Security and Production Rules
- Enforce tenant isolation via RLS; never join cross-tenant data without checks.
- Protect customer data; mask PII in logs and analytics.
- Use HTTPS strictly; enforce secure cookies; implement HSTS.
- Rotate API keys and secrets automatically; monitor for key leakage.
- Validate and restrict file uploads; scan for malware.

Testing Checklist
- Unit: domain models, validators, and utility functions.
- Integration: DB access, API routes, and Stripe webhooks.
- E2E: user flows from signup to dashboard interactions.
- Performance: basic latency checks on critical endpoints; ensure server components are properly cached.
- Security: basic vulnerability scans and dependency checks in CI.

Common Mistakes to Avoid
- Skipping server-side validation; relying on client-only checks.
- Mixing business logic into UI layers.
- Ignoring multi-tenant data isolation and RBAC.
- Neglecting test coverage for AI scoring paths and webhooks.
- Not documenting architecture decisions or losing configuration in code.

FAQ

  
    What is a CLAUDE.md Template?
    A copyable CLAUDE.md template that codifies engineering rules for a stack-specific SaaS project, enabling consistent Claude Code guidance.
    Which stack does this template cover?
    Next.js with TypeScript, Supabase, Clerk, Stripe, plus AI vendor scoring, delivery risk, and procurement dashboards.
    How do I customize AI vendor scoring in this template?
    Modify the scoring service to call your AI models, store scores in a versioned table, and expose results via the procurement dashboard.
    How do I deploy to production securely?
    Use a hosting provider (e.g., Vercel), configure environment variables, set up Stripe webhooks, and enable RBAC and RLS in Supabase.
    What are the key pitfalls to avoid?
    Avoid client-only validation, exposing secrets, and bypassing server-side business logic or RBAC rules.
  


Related implementation resources: AI Use Case for Ui/Ux Agencies Using Hotjar Heatmaps To Identify Where Website Visitors Experience Friction or Confusion and Designing secure Server Actions with mandatory input schema validations at the server boundary.