SvelteKit + CockroachDB + NextAuth.js + Prisma ORM Architecture - CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md Template provides a copyable CLAUDE.md block and concrete guidance for building a full-stack app using SvelteKit, CockroachDB, NextAuth.js inspired authentication flow, and Prisma ORM. It covers architecture decisions, file layout, validation, security, tests, and deployment considerations specific to this stack.

The template is tailored for a SvelteKit project that uses CockroachDB as the data store, Prisma ORM for data access, and an NextAuth.js style authentication flow adapted for SvelteKit. It includes rules, do nots, and explicit file-structure guidance to keep architecture clean and production-ready.

When to Use This CLAUDE.md Template

• When standardizing a SvelteKit app architecture backed by CockroachDB via Prisma
• When you need a ready-to-paste CLAUDE.md that defines project roles, constraints, and deployment requirements
• When configuring a NextAuth.js inspired authentication flow in a SvelteKit environment
• When you require explicit security, validation, and migration guidelines for this stack

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code acting as a senior full-stack architect for a SvelteKit app with CockroachDB, Prisma ORM, and a NextAuth.js inspired authentication flow. Your output must be a complete CLAUDE.md for this stack.

Architecture rules:
- Build a modular SvelteKit app with a Prisma-backed data layer and a server-side authentication flow compatible with NextAuth.js style adapters.
- Connect to CockroachDB using Prisma with a Postgres-compatible datasource and enable CockroachDB preview features for optimal compatibility.
- Centralize authentication, authorization, and session management in dedicated server routes and hooks; avoid leaking auth logic to UI components.
- Ensure environment-specific configuration via environment variables; never hardcode secrets.
- Maintain a single source of truth for validation, authorization, and policy decisions.

File structure rules:
- src/routes with explicit +page and +server entry points for pages and APIs
- src/lib for shared utilities (db.ts, auth.ts, validation.ts)
- prisma/schema.prisma with migrations folder
- .env for secrets (excluded from version control)

Authentication rules:
- Use a NextAuth.js style adapter pattern compatible with SvelteKit
- Use secure cookies, HttpOnly, SameSite strict; rotate session tokens periodically
- Validate sessions server-side on protected routes
- Do not expose access tokens to the client beyond what is necessary for auth flows

Database rules:
- CockroachDB as the primary database via Prisma
- Use migrations; avoid embedding credentials; pull from environment variables
- Define clear models with indices for read-heavy access patterns

Validation rules:
- Validate payloads on the server with a strict schema (eg zod)
- Return deterministic, actionable error messages for clients

Security rules:
- Do not log sensitive data; redact in logs
- Enforce TLS, CSRF protection, and strict CORS on API routes
- Prohibit client-side access to secrets and DB credentials

Testing rules:
- Unit tests for Prisma queries and adapters
- Integration tests covering auth flows and protected routes
- E2E tests for login, data access, and edge cases

Deployment rules:
- Use environment variables for DB URL and secrets; do not commit them
- Run migrations during deployment before starting the app
- Ensure CockroachDB connection is resilient with automatic retries

Things Claude must not do:
- Do not propose non-existent adapters for SvelteKit
- Do not bypass server-side checks for protected routes
- Do not use client-side storage for sensitive session data

Recommended Project Structure

project-root/
├─ prisma/
│  ├─ schema.prisma
│  └─ migrations/
├─ src/
│  ├─ hooks.server.ts
│  ├─ app.html
│  ├─ lib/
│  │  ├─ db.ts
│  │  └─ auth.ts
│  ├─ routes/
│  │  ├─ +layout.server.ts
│  │  └─ api/
│  │     └─ auth/
│  │        └─ [...nextauth].ts
│  └─ routes/
└─ .env.example

Core Engineering Principles

• Explicit architecture boundaries and single responsibility across layers
• Security-first by default with validated inputs and protected routes
• Idempotent migrations and deterministic deployments
• Type-safe data access via Prisma and strict runtime validation
• Observability through clear logging and tracing in auth and DB interactions

Code Construction Rules

• Use TypeScript throughout the stack
• Prisma ORM with CockroachDB via a Postgres-compatible datasource and cockroachdb preview feature
• Server-side validation for all API routes using a schema library (eg zod)
• Authentication logic centralized in server hooks and a NextAuth.js like adapter for SvelteKit
• Do not hardcode credentials; read from environment variables
• Keep client-side code free from secrets and DB interaction logic

Security and Production Rules

• Use TLS, HttpOnly and Secure cookies; SameSite strict
• CSRF protection on state-changing requests
• Do not log sensitive data; redact secrets
• Migrate and seed databases only in controlled environments
• Limit DB user permissions to required actions

Testing Checklist

• Unit tests for Prisma queries and model hooks
• Integration tests for auth flows and protected endpoints
• End-to-end tests for login, session handling, and data access
• Migration tests to ensure schema upgrades are safe

Common Mistakes to Avoid

• Assuming NextAuth.js works out of the box with SvelteKit without adapter wiring
• Storing secrets in client-side code or environmentless builds
• Skipping migrations or not validating inputs on the server
• Under-protecting routes that access sensitive data

FAQ

• Is this CLAUDE.md Template applicable to production?

  Yes, with proper environment configs, migrations, and security hardening as described above.

• Can I adapt NextAuth.js flows for SvelteKit?

  Yes, use a NextAuth.js inspired adapter pattern and server hooks for session management.

• Which database and ORM are used?

  CockroachDB as the database with Prisma ORM for data access and migrations.

• How are credentials stored?

  Only in environment variables or secret management; never in client code or repo.

• What testing should be prioritized?

  Unit tests for data access, integration tests for auth, and end-to-end tests for critical workflows.