Express.js + PlanetScale MySQL + Kinde Auth + Prisma ORM Async Core Layout — CLAUDE.md Template

Overview

This CLAUDE.md Template demonstrates a production-ready Express.js API that uses PlanetScale MySQL as the data store, Kinde Auth for authentication, Prisma ORM for data access, and an Async Core Layout to organize services, controllers, and repositories. It is designed as a copyable CLAUDE.md template page you can paste into CLAUDE Code to generate scaffold code and ensure consistent architecture.

Direct answer: Build a scalable Express API with Prisma + PlanetScale, secured by Kinde Auth, following an Async Core Layout for clear, testable boundaries.

When to Use This CLAUDE.md Template

• You need a Node.js API using Express.js with a scalable MySQL backend hosted on PlanetScale.
• You require authentication via Kinde Auth for protected endpoints and user management.
• You want a clean architecture that separates concerns with a Prisma-driven persistence layer and an Async Core Layout.
• You plan to deploy to a containerized environment with a robust testing strategy.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code. Produce an Express.js API scaffold that uses Prisma ORM to talk to PlanetScale MySQL, integrates Kinde Auth for authentication, and follows an Async Core Layout. The output must be a runnable blueprint for engineers to paste into a repository.

Architecture rules:
- Layered architecture: api (controllers & routes), domain (services), persistence (repositories), and infra (config, auth, environment).
- Prisma ORM as the single source of truth for data access; all data operations go through repositories.
- Async Core Layout: use async/await for all IO, centralize error handling, and avoid top-level try/catch in business logic.
- Use environment-driven configuration; no hard-coded secrets.
- Use a single PrismaClient instance per request lifecycle when possible; ensure proper disconnection on shutdown.
- All routes with explicit HTTP verbs and status codes; endpoints are versioned (e.g., /api/v1).
- Use Kinde Auth tokens for protected endpoints; validate token in middleware before business logic.

File structure rules:
- src/
  - api/
    - controllers/
    - routes/
  - domain/
    - services/
  - persistence/
    - repositories/
  - infra/
    - auth/
    - config/
  - prisma/
  - validation/
  - tests/
- prisma/schema.prisma
- .env.example
- package.json
- Dockerfile
- README.md

Authentication rules:
- Protect routes with a Bearer token from Kinde Auth; validate and attach user to the request.
- Don’t process protected requests without a valid token or with expired tokens.
- Store only non-sensitive user identifiers in tokens; never store passwords.

Database rules:
- PlanetScale MySQL via Prisma; set DATABASE_URL in .env; use a dedicated test DB for tests.
- Use migrations through Prisma (npx prisma migrate deploy) in CI/CD; do not auto-migrate in production.
- Enable connection pooling per Prisma recommendations and ensure proper retry strategy.

Validation rules:
- Use Zod for runtime validation of all inputs (params, query, body).
- Centralize validation schemas in src/validation; reuse across controllers.

Security rules:
- Use helmet and CORS with a restricted origin policy in production.
- Do not log secrets; mask sensitive fields in logs.
- Enforce CSRF protection only if you expose cookies; for API tokens, rely on stateless JWT validation.
- Disable X-Powered-By header.

Testing rules:
- Unit tests for services and repositories; integration tests for the API endpoints with supertest.
- Tests should mock Prisma where appropriate; use a separate PlanetScale test database.
- CI should run lint, type checks, unit tests, and integration tests before merge.

Deployment rules:
- Write a multi-stage Dockerfile using Node.js 18+; run as non-root; expose port 3000 by convention.
- Use docker-compose for local development with a PlanetScale emulator or a test instance and a Kinde mock if available.
- Use environment variables for all secrets and configuration; do not bake secrets into images.

Things Claude must not do:
- Do not bypass authentication or authorization checks.
- Do not embed database credentials or API keys in code.
- Do not generate in-repo migrations in a way that could affect production data without review.
- Do not assume Prisma automatically handles migrations in production.
- Do not skip input validation or error handling in endpoints.

Recommended Project Structure

express-api/
├── src/
│   ├── api/
│   │   ├── controllers/
│   │   └── routes/
│   ├── domain/
│   │   └── services/
│   ├── persistence/
│   │   └── repositories/
│   ├── infra/
│   │   ├── auth/
│   │   └── config/
│   ├── prisma/
│   ├── validation/
│   └── tests/
├── prisma/
│   └── schema.prisma
├── .env.example
├── Dockerfile
├── package.json
└── README.md

Core Engineering Principles

• Clear separation of concerns with a durable Async Core Layout.
• Type safety and explicit contracts using TypeScript and input validation (Zod).
• Infrastructure as code: environment-driven configuration and reproducible builds.
• Security-first: authenticated endpoints, encrypted secrets, and minimal exposure.
• Testable by default: unit, integration, and end-to-end where feasible.
• Observability: structured logging, traceable requests, and meaningful error messages.

Code Construction Rules

• Use TypeScript for all source files; enable noImplicitAny, strictNullChecks, and strict mode.
• Instantiate PrismaClient with proper lifecycle management to avoid connection leaks.
• Maintain a repo pattern for data access; all queries go through repositories.
• Validate inputs with Zod before any business logic invocation.
• Protect endpoints with Kinde Auth and verify scopes/roles in middleware where required.
• Use async/await everywhere; avoid callback hell and unhandled promise rejections.

Security and Production Rules

• Environment variables must be stored securely; do not commit secrets to VCS.
• Enable Helmet, CORS with restricted origins; log requests but scrub sensitive data.
• Use TLS in production; enforce secure cookies when using cookies for auth fallback.
• Limit request rates to prevent abuse; implement input size limits and rate-limiting.

Testing Checklist

• Unit tests for services and repositories with mocked Prisma clients.
• Integration tests for controllers using Supertest; exercise authentication flows with Kinde mocks.
• End-to-end tests where possible against a test PlanetScale instance.
• CI should run type checks, lint, unit tests, and integration tests before merging.

Common Mistakes to Avoid

• Hardcoding secrets or credentials in code or config files.
• Skipping authentication on sensitive endpoints or misconfiguring Kinde scopes.
• Assuming Prisma auto-migrates in production; use explicit migrations in CI/CD.
• Overloading middleware without proper error handling and timeouts.

FAQ

• What is the target stack for this CLAUDE.md Template?

  Express.js with Prisma ORM connected to PlanetScale MySQL, integrated with Kinde Auth, following Async Core Layout.

• Which files should I customize first?

  Start with prisma/schema.prisma, src/infra/config, src/api/routes and src/api/controllers; add authentication and validation schemas in src/validation.

• How do I run migrations safely?

  Use npx prisma migrate deploy in CI to apply migrations against PlanetScale test DB. Do not run deploy migrations in production without review.

• How is authentication enforced?

  Requests to protected endpoints must include a valid Bearer token from Kinde; a middleware validates and attaches user info.

• How do I test this template?

  Write unit tests for services with mocked Prisma, integration tests for endpoints with Supertest, and run end-to-end tests against a test PlanetScale environment.