CLAUDE.md template for Next.js 16 + Apache Cassandra + Clerk Auth + Express-Cassandra ODM Configuration | CLAUDE.md Template

Overview

A CLAUDE.md template page for Next.js 16 + Apache Cassandra + Clerk Auth + Express-Cassandra ODM. It targets developers building full-stack apps with a modern React frontend, a columnar NoSQL store, and robust authentication.

Direct answer: This page delivers a copyable Claude Code block and stack-aware guidance you can paste into CLAUDE.md to scaffold a production-ready project.

When to Use This CLAUDE.md Template

• You need a ready-to-paste CLAUDE.md template for a Next.js 16 app with a Cassandra backend.
• You want Clerk-based authentication wired into Next.js route handling.
• You require Express-Cassandra ODM for data modeling and queries.
• You need a predictable project structure and explicit security, validation, and deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a software architect building a Next.js 16 app with Apache Cassandra as the data store, Clerk for authentication, and an Express-Cassandra ODM for data modeling and access.

Architecture rules:
  - Use Next.js 16 app directory (or pages if you prefer) with server components where appropriate.
  - Data access via Express-Cassandra ODM tied to a Cassandra cluster (or Astra with DataStax API if available).
  - Clerk authentication for all user-facing routes; protect API routes with Clerk guards.
  - Centralized environment configuration via .env.local; never commit secrets.
  - Stateless API routes; data fetches should be idempotent where possible.
  - Logging and tracing enabled in production; redact personal data in logs.
  - Use TypeScript for API contracts and strong typing in model definitions.

File structure rules:
  - apps/web/ for Next.js application code
  - cassandra/models/ for ODM models
  - cassandra/orm.js for Express-Cassandra setup
  - clerk/ for Clerk middleware and hooks
  - server/index.js for any custom Node server glue (if used)
  - .env.local.sample in repo root for quick onboarding

Authentication rules:
  - Integrate Clerk with Next.js via middleware and client components
  - Enforce session checks on pages/api and app routes that access user data
  - Store only public user identifiers in client state; never expose tokens

Database rules:
  - Connect to Cassandra using Express-Cassandra ODM; manage keyspace and tables via migrations where possible
  - Use prepared statements or parameterized queries; guard against SQL/CQL injection
  - Enforce schema at the ODM level; validate data types before persistence

Validation rules:
  - Validate input on both client and server sides; never rely solely on client-side validation
  - Use Joi (or Zod) schemas for request payload validation where appropriate
  - Normalize and sanitize inputs before persistence

Security rules:
  - Do not expose database credentials in frontend code
  - Use HTTPS in all environments; enable HSTS in production
  - CSRF protection for state-changing requests; ensure tokens are short-lived
  - Do not bypass authentication/authorization checks on critical endpoints

Testing rules:
  - Unit tests for ODM models and data validators
  - Integration tests for API routes with Clerk mock
  - End-to-end tests simulating auth flows and data writes/reads
  - CI should run tests on pull requests and on main

Deployment rules:
  - Deploy with environment variables: CASSANDRA_CONTACT_POINTS, KEYSPACE, CLERK_API_KEY, etc.
  - Use a stable Node.js runtime; pin to a supported version
  - Use a cloud provider or hosting that supports Next.js 16 app directory plus API routes and optional custom server glue
  - Ensure Cassandra cluster is reachable from the deployment environment
  - Monitor health endpoints and set up alerts for critical failures

Things Claude must not do:
  - Do not generate code that bypasses Clerk authentication checks
  - Do not rely on client-side secrets for DB access
  - Do not mix Prisma, Mongoose, or other ORMs not part of this stack
  - Do not assume in-cluster Cassandra by default; verify connection details in environment

Recommended Project Structure

project/
├── apps/
│   └── web/
│       ├── app/
│       │   ├── layout.js
│       │   └── page.js
│       ├── components/
│       └── next.config.js
├── cassandra/
│   ├── models/
│   │   └── user.js
│   └── orm.js
├── clerk/
│   └── middleware.js
├── server/
│   └── index.js
└── README.md

Core Engineering Principles

• Clear separation of concerns between frontend (Next.js) and backend data access (Express-Cassandra ODM).
• Idempotent API routes and deterministic data access patterns.
• Explicit authentication and authorization boundaries using Clerk.
• Type-safe contracts for API payloads (TypeScript) and ODM models.
• Environment-driven configuration with validated schemas.

Code Construction Rules

• Use the provided CLAUDE.md template block verbatim as a starting point for code generation.
• All database connections must be initialized in a single module (e.g., cassandra/orm.js).
• All API routes must validate inputs with a strict schema before persistence.
• Authentication checks must occur on every protected route or API handler.
• Avoid introducing any ORM not part of this stack (Prisma, Mongoose, etc.).
• Do not hard-code credentials; use environment variables with safe defaults where possible.

Security and Production Rules

• Enforce HTTPS and HSTS in production; disable debug logs in prod.
• Use secure, HttpOnly cookies for Clerk sessions; rotate keys regularly.
• Audit and redact PII in logs; implement access controls on data exposure.
• Limit Cassandra permissions to least privilege for the app role.

Testing Checklist

• Unit tests for ODM models and data validators.
• Integration tests for Clerk-authenticated routes.
• End-to-end tests simulating sign-in, data writes, and reads.
• Performance tests for Cassandra read/write latency under load.
• CI validates code style, type checks, and security checks.

Common Mistakes to Avoid

• Relying on client-side validation alone for security-critical data.
• Using Prisma/Mongoose in a setup designed for Express-Cassandra ODM.
• Exposing database credentials or Clerk secrets in frontend code.
• Skipping authentication on endpoints that access user data.

FAQ