Remix Framework + PlanetScale MySQL + Clerk Auth + Prisma ORM Architecture — CLAUDE.md Template

Overview

The CLAUDE.md template provides a copyable Claude Code instruction block tailored for a Remix Framework app backed by PlanetScale MySQL, Clerk authentication, and Prisma ORM. It helps teams articulate architecture decisions, guardrails, and implementation rules in a single, paste-ready document.

When to Use This CLAUDE.md Template

• Starting a new Remix project with a scalable MySQL backend on PlanetScale.
• Integrating Clerk for authentication across routes and loaders.
• Establishing a type-safe data layer with Prisma ORM and Prisma Client.
• Publishing architecture constraints to guide future contributors and Claude Code usage.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, a copyable CLAUDE.md template author for Remix + PlanetScale + Clerk + Prisma stack.
- Your goal is to produce practical, production-ready Claude Code for this exact stack.

Architecture rules:
- Separate concerns: web layer (Remix routes) + business logic layer + data access (Prisma).
- Favor server components and server actions for mutations.
- Use PlanetScale branch-friendly migrations and avoid destructive operations in production.

File structure rules:
- Keep a single source of truth for config in .env/.env.local; never commit secrets.
- Prisma schema at prisma/schema.prisma; migrations stored in prisma/migrations.
- Remix app under app/ with routes, components, and libs clearly separated.
- Clerk config under clerk/ and environment-controlled keys in .env.

Authentication rules:
- Use Clerk provider at app level; protect routes with Clerk middleware or route guards.
- Do not store session tokens in localStorage; rely on secure httpOnly cookies managed by Clerk.
- Validate sessions on the server side before performing data mutations.

Database rules:
- Use PlanetScale MySQL; connect via DATABASE_URL in .env.
- Prefer prisma migrate deploy in CI for production branches; seed data with seed scripts when appropriate.
- Avoid hard-coded credentials; pull connection strings from environment variables.

Validation rules:
- Validate input with a typed schema (prefer Zod or similar) and integrate with Remix forms on the server.
- Enforce required fields and correct data shapes before any Prisma operations.

Security rules:
- Enable CSRF protection for forms; rely on SESSION cookies with httpOnly and Secure flags.
- Scan dependencies for known vulnerabilities and pin versions.
- Use role-based access control for sensitive routes.

Testing rules:
- Unit test validators and Prisma client usage with mock data.
- Integrate tests for Clerk authentication flows.
- End-to-end tests cover login, protected routes, and data mutations.

Deployment rules:
- Deploy Remix to a serverless-friendly host; ensure PlanetScale production branch is selected.
- Set environment variables in the hosting environment (.env-like in the host UI).
- Run migrations in CI before deploy; verify migrations succeed in staging.

Things Claude must not do:
- Do not generate Mongoose-specific or non Prisma code.
- Do not bypass Clerk authentication guards or expose secrets in code.
- Do not propose client-side DB access or direct DB credentials in UI code.

Recommended Project Structure

remix-planet-scale-prisma-clerk/
├── .env.example
├── package.json
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── clerk/
│   └── config.ts
├── app/
│   ├── entry.client.tsx
│   │   └── ...
│   ├── entry.server.tsx
│   ├── root.jsx
│   ├── components/
│   │   ├── Layout.jsx
│   │   └── NavBar.jsx
│   ├── routes/
│   │   ├── index.tsx
│   │   ├── dashboard.tsx
│   │   └── _auth.tsx
│   └── lib/
│       ├── prisma.ts
│       └── clerk.ts
├── public/
│   └── global.css
└── README.md

Core Engineering Principles

• Clarity over cleverness: explicit architecture decisions and rules.
• Type safety everywhere: TypeScript, Prisma types, and validated inputs.
• Security by default: secure cookies, proper auth guards, and minimal surface area.
• Deterministic testing and CI: automated checks for migrations, tests, and linting.
• Single source of truth: environment-based configuration and consistent deployment pipelines.

Code Construction Rules

• Use Remix route modules for pages and server actions for mutations.
• Integrate Prisma via a generated client with strict type-safe queries.
• Store secrets in environment variables only; never hard-code in code or CLAUDE.md blocks.
• All auth checks must occur on the server; avoid leaking user data to the client.
• Keep CLAUDE.md blocks as the single source of architecture guidance for this stack.

Security and Production Rules

• Clerk authentication is the gatekeeper for protected routes.
• HTTP cookies must be httpOnly, Secure, and SameSite=Lax or Strict as appropriate.
• Use PlanetScale branch-aware migrations and avoid destructive migrations in production.
• Monitor dependencies and apply security patches promptly.

Testing Checklist

• Unit tests for validators and utility functions.
• Integration tests for Prisma queries and Clerk auth flows.
• End-to-end tests covering login, protected pages, and data mutations.
• CI checks for type safety, linting, and migrations on PRs.

Common Mistakes to Avoid

• Mixing Mongoose with Prisma in the same project.
• Storing secrets in client-visible code or CLAUDE.md blocks.
• Neglecting PlanetScale branch management and migration best practices.
• Under-securing auth cookies or skipping server-side auth checks.

FAQ